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Preface 


This book should prove to be a valuable reference as well as an informative 
tutorial. There is no other book like this available today. It is intended 
to clear away some of the mystery of how program source files turn into 
program files (executables) and Dynamic Link Libraries (DLLs). This book 
will explain how all the files in the process of building a running program 
are created and take a close look at how they are structured. 

This book is certainly not for every programmer or computer user. There 
are many who can do quite well without ever knowing about the subjects 
this book discusses. If, however, you are a program tool writer, a computer 
science student, a technical support person or just plain curious, this is a 
book for you! You will be shown the fundamentals and how to get even 
more detail if you want it. As we progress, you will be introduced to many 
of the tools in the OS/2 Warp Toolkit and learn some interesting techniques 
for their use. 

We begin in the first chapter by examining an object file (.OBJ) which is 
created by a compiler or assembler. You will learn that an object file is made 
up of many pieces of information and what those bits of information are used 
for later in the process. We provide a tool (DECODE.EXE) that will allow 
you to break the object file up into its individual records and enable you to 
examine them as you read the material. 

In chapter two, we look at library files (.LIB) and discuss the differences 
and trade offs between static and dynamic linking. You will learn how 
libraries are created and maintained and you will see their relationship to 
object files. We’ll discuss import libraries and how they are used to create 
dynamic link libraries and you will actually create a dynamic link library 
containing a function of your own. You’ll also learn how to create a dynamic 
link library without an import library. At the end of the chapter, we will use 
the DECODE.EXE tool to take a look inside of a library file and see how it 
is put together. 

The linker is a very important program in the path from source to exe¬ 
cutable. In chapter three we take a close look at the linker, the program 
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that takes all the pieces and puts them together to make the final product, an 
executable program. We’ll tell you how the linker structures its output into 
a format the operating system needs to load and run the executable program. 

We then move on and dissect the executable module itself. We discuss how 
to locate and interpret the executable header. The different fields of the header 
are discussed and we introduce you to a tool (EXEHDR.EXE) found in the 
OS/2 Warp Toolkit that will provide you with a wealth of information about 
your executables and dynamic link libraries. You will learn how dynamic 
link libraries differ from other executables and how code inside them is 
resolved (located) by the operating system. We will show you how to use 
FWDSTAMP.EXE, another useful tool in the Toolkit, to replace a function 
within a DLL or to replace an entire DLL in an application without the 
necessity of rebuilding the application. 

Chapter five goes into greater detail about EXEHDR.EXE and the output it 
generates. You will learn how EXEHDR.EXE displays valuable information 
from the executable header and what that information tells you. You’ll leam 
about relocation and fixups. We’ll show you how they get from your object 
modules into the executable program and how the operating system uses that 
information to make your programs run properly. 

Chapter six is sort of a catch all chapter. In chapter six we discuss some 
topics that relate to the other topics in the book but don’t require a chapter 
of their own. We will show you, for example, what happens to a program 
file if you turn on a flag in the compiler to tell the compiler and linker to 
enable debugging. You’ll be introduced to the a very powerful tool, the 
kernel debugger. We’ll tell you about OS/2’s dynamic link libraries and 
show you how OS/2 is able to locate the proper code no matter which library 
it is in. Included is also a discussion about how OS/2 maintains backward 
compatibility to previous (16-bit) versions. We’ll show you an example of a 
16-bit program calling 32-bit functions as well as a 32-bit program calling 
16-bit functions. 

Finally in chapter 7, the DECODE.EXE tool is discussed. The source code 
is provided for easy modification to suit your own needs. This source as well 
as source, makefiles and executables for all the samples are also provided on 
the accompanying diskette. 

We have assumed that you are familiar with programming and have a C 
or C++ compiler. For the samples in the book, we used the IBM C Set++ 
compiler but have been careful to use only functions that are supplied with 
most commercially available compilers thereby making the samples portable 
to most compilers. Although several of the tools discussed are part of the 
OS/2 Toolkit, (which is available on the IBM Developer Connection or as a 
separate product) most of the material can be easily understood without the 
tools themselves. 

No matter what your experience is with OS/2, we feel there is something 
to be learned from this book. We have tried to cover some very technical 



information in a manner that will give you the basics but not bore you with 
every last detail. It is not our intention to teach you how to program. For 
that reason our samples are extremely simple but we have insured that they 
show the point of the accompanying text. 

Now jump in and enjoy! 




1 

Object (.OBJ) Files 


There are many drivers who get behind the wheels of their cars, start them 
up, drive from point A to point B and never give a thought to all the little 
things that occur to make it happen. The job gets done. It’s not necessary to 
understand the details. Then there are those who like to lift the hood, look 
around, tinker and understand what makes the wheels turn. 

There is an analogous group of computer professionals who work their 
entire career knowing that running programs are created from source files, 
but never bother to “lift the hood,” so to speak, and look inside to see how 
it all happens. Can we live without that information? Sure, most of us can, 
but there is a group of people who either must know it or are just curious. 
This group is the target audience for this book. 

Those who read it will gain valuable information about the makeup of the 
files they run on their computer. They will understand the relationship be¬ 
tween a compiler and a linker and gain insight about how an operating system 
loads and runs programs. Together we will explore how the actual files are 
put together and convey information. We will follow program creation from 
its source through its intermediate steps and finally to its executable format. 
We will learn about various types of libraries, their makeup and their use. 

Easy sample programs illustrate the points in the text. An original tool 
that will allow you to closely examine the files, and its source, are provided. 


1.1 Our First Sample Program 

We’ll start off in the middle. That is, somewhere between the places where 
most progr ammi ng books start off and where they eventually take you. Most 
books talk about how to write a program or what to do with it after it is all 
put together. We’re going to start by learning what happens to your program 
after you write it but before it really becomes an executable program. After 
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1. OBJECT (.OBJ) FILES 


you write your program source, the next step is to compile it, and an object 
module ( .OBJ file) is created. That will be our starting point. 

In order to make it easier to understand what goes on during the creation of 
a program, we believe the samples we use as we progress through this book 
should be simple, yet contain enough information for you to understand the 
topic. 


1.2 How Do We Build It? 


A Note About Tools and Samples 

All of the samples in this book are included on the accompanying 
diskette. Most samples have makefiles for your convenience. Each 
sample is in its own directory. There is a README file in the root 
directory of the diskette. We have also included the object files, ex¬ 
ecutables and other files mentioned in the text such as EXEHDR. EXE 
output. If you want to copy the samples to your fixed disk, you can 
use the OS/2 XCOPY command. This should only be necessary if 
you plan to recompile or experiment with the samples. We make the 
assumption that you are familiar with the C programming language, 
have a C compiler installed and that your environment variables are 
set up correctly to perform compilations. Refer to your compiler 
user’s guide for the proper settings. We used the IBM C Set++ com¬ 
piler, but with only standard ANSI C library functions, so it should 
be easy to port the samples to work with any popular C compiler. 
The OS/2 tools we used, such as LINK386.EXE, EXEHDR.EXE and 
FWDSTAMP. EXE are the versions on the most recent Developer Con¬ 
nection for OS/2 which is a subscription service from IBM aimed 
specifically at software developers. As of this writing, Developer 
Connection Volume #8 is the current release. For further details call 
toll free at 1-800-6DEVCON (1-800-633-8266). While desirable, 
most of the material in this book does NOT require the tools. All 
samples include source and running executables. 


We will start by taking a simple C source file and creating an .OBJ file 
we can take a closer look at. If we don’t stop the process after creation of 
the .OBJ, an executable program will be created that will write the word 
“Hello” to the screen. For the purposes of this chapter, we will only partially 
complete the process. With this, as with any sample provided, please feel 
free to experiment. 
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Here is the source for our first sample. You can create it with your favorite 
text editor: 

/* SMP1.C */ 

#include <stdio.h> 

main() 

{ 

printf("Hello\n"); 

} 

If you are using the IBM C Set++ compiler, you can compile SMP1. C with 
the following command: 

icc /c smpl.c 

The /c is a compiler option or switch that tells the compiler to produce 
only an . OB 3 without invoking the linker. We will talk more about the linker 
later. It is the program that takes our .OB3 and turns it into an executable 
program, a . EXE. 

You can use any compiler that produces code acceptable to OS/2. Most 
of the details discussed in this book are applicable to DOS as well however; 
we are using OS/2 Warp as our reference. The results of the compilation 
may vary slightly, but should be similar enough that you shouldn t have any 
difficulty following along. 

The output from the compiler run will be a small .OBJ file, SMP1.0BJ. 
When we compiled it as a test, the . OBJ was 282 bytes in size. Yours should 
be around that size also. 


1.3 Now That We Built It, What Is It? 

We’ve managed to compile SMP1. C and we are left with a file with an . OB J 
extension. What is it? What do we do with it? 

Source code can be seen as the blueprint for the program and object files 
(.OBJ files) as the building blocks. We put the building blocks together to 
make the final product, your executable program. This book will explain a 
little of the mystery of how it all happens. Actually, it’s not too mysterious, 
but there has been virtually nothing written about the details and we think 
you will probably find them interesting. 

The .C file and .OBJ file are the first and second steps toward the final 
product. We are going to examine this .OBJ and see how it is put together. 
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1. OBJECT (.OBJ) FILES 


Understanding this will make the information presented in later chapters 
much clearer. 

A compiler or an assembler produces a . OB J when it processes your source 
code. The . OBJ hie contains code that represents all the variables and func¬ 
tion calls you entered into your source code, but it is still not a runable 
program. You have to process the .OBJ hie with another program, called 
the linker, possibly combining this .OBJ module with other .OBJ modules 
that will ht together to make your hnal program. The linker will resolve all 
the references to runtime static and Dynamic Link Library (DLL) functions 
and do some other magic to the code that will eventually be your running 
executable. We’ll take a closer look at this process in later chapters. 

Figure 1.1 Shows the relationship between source hies (.C), a compiler 
and object (.OBJ) hies. 


srca.c 



—> 

srca.obj 




srcc.c 



—> 

srcc.obj 


FIGURE 1.1 

Relationship between source files (. C), a compiler and object (. OB J) files. 

An .OBJ file is a binary file made up of a series of records which are 
put into the .OBJ by the compiler, each of which defines a specific piece of 
information. The first record is called the THEADR record. That stands for 
Translator HEAD er Record. It identifies what follows as a valid object module. 
The different types of records are important when our .OBJ module(s) are 
processed by the linker. The linker actually builds the running program based 
on the information contained in the records in the .OBJ modules. 

There are about 40 different record types. The linker uses the information 
contained in these records to create the correct code and address references 
in the final, running program. We will see more about how the linker does 
this in later chapters, but first let’s take a look at the different types of records. 

Each record has its own format and conveys a different piece of informa¬ 
tion. The record types are listed in Figure 1.2. Note that there are many 
variations of the COMENT type record (88H) and that some record types have 
two different hexadecimal type identifiers. The reason for two possible 
types for some records is that some of the numeric fields in these records can 
contain either 16-bit or 32-bit values. The odd record types contain 32-bit 


srcb.obj 
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(HEX) 

Type 

80H 

THEADR 

82H 

LHEADR 

88H 

COMENT 


Translator Header Record 
Library Header Record 
Comment Record 


NOTE: The COMENT record type is broken down by class and subtype. For 
clarity we have listed the COMENT class and subtype separately as follows: 

COMENT CLASS VALUES 


0 Translator (Which language or compiler) 

1 Intel Copyright 

2-9B Intel Reserved 

81 Library Specifier (Obsolete) 

9C MS-DOS Version (Obsolete) 

9D Memory Model 

9E DOSSEG (Tells Linker to use D0S-0S/2 
naming conventions) 

9F Default Library Search Name 
AO OMF Extensions 

Sub-Types (See Below for explanation) 


01 IMPDEF 
02 EXPDEF 
OS INCDEF 

04 Protected Memory Library 
05 LNKDIR 

06-FF Reserved for Microsoft 
A1 Symbolic Debug Information 

A2 Link Pass 

A3 LIBMOD 

A4 EXESTR 

A6 INCERR 

A7 NOPAD 

A8 WKEXT 

A9 LZEXT 

AA PHARLAP 

AF IDMDLL 

B2-BF Unused 

CO-FF Reserved for User defined comment classes. 


FIGURE 1.2 
Record Types. 
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88H 

IMPDEF 

Import Definition Record 






(Comment Class AO, Subtype 

01) 



88H 

EXPDEF 

Export Definition Record 






(Comment Class AO, Subtype 

02) 



88H 

INCDEF 

Incremental Compilation Record 





(Comment Class AO, Subtype03) 



88H 


Protected Mode DLL 






(Comment Class AO, Subtype 

04) 



88H 

LNKDIR 

C++ Directives Record 






(Comment Class AO, Subtype 

05) 



88H 


Symbolic Debug Information 

(Comment 

Cl ass 

Al) 

88H 


Link Pass 

(Comment 

Class 

A2) 

88H 

LIBMOD 

Library Module Name Record 

(Comment 

Class 

A3) 

88H 

EXESTR 

Executable String Record 

(Comment 

Cl ass 

A4) 

88H 

INCERR 

Incremental Compilation Error (Comment 

Class 

A6) 

88 H 

NOPAD 

No Segment Padding 

(Comment 

Cl ass 

A7) 

88H 

WKEXT 

Weak Extern Record 

(Comment 

Class 

A8) 

88H 

LZEXT 

Lazy Extern Record 

(Comment 

Class 

A9) 

88H 


PharLap Format Record 

(Comment 

Class 

AA) 

88H 

IDMDLL 

Identifier Manipulator 

(Comment 

Class 

AF) 


8AH or 8BH MODEND Module End Record 

8CH EXTDEF External Names Definition Record 

90H or 91H PUBDEF Public Names Definition Record 

94H or 95H LINNUM Line Number Record 

96H LNAMES List of Names Record 

98H or 99H SEGDEF Segment Definition Record 

9AH GRPDEF Group Definition Record 

9CH or 9DH FIXUPP Fixup Record 

AOH or A1H LEDATA Logical Enumerated Data Record 

A2H or A3H LIDATA Logical Iterated Data Record 

BOH COMDEF Communal Names Definition Record 

B2H or B3H BAKPAT BackPatch Record 

B4H or B5H LEXTDEF Local External Names Definition Record 
B6H or B7H LPUBDEF Local Public Names Definition Record 
B8H LCOMDEF Local Communal Names Definition Record 

C2H or C3H COMDAT Initialized Communal Data Record 
C4H or C5H LINSYM Symbol Line Numbers Record 
C6H ALIAS Alias Definition Record 

C8H or C9H NBKPAT Named BackPatch Record 


FIGURE 1.2 (continued) 
Record Types. 
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values; the even record types contain 16-bit. (This has nothing to do with the 
Usel6 or Use32 segment attributes in a SEGDEF record, which are the only 
way to distinguish a segment using 16-bit addressing from one using 32-bit 
addressing.) 

It is beyond the scope of this book to go into detail about each and every 
one of these types. We will, however, discuss a couple of them, and you 
will see that there are similarities in their format. Detailed information can 
be found in the IBM OS/2 16/32-bit Object Module Format (OMF) and 
Linear executable Module Format (LX) document available to interested 
developers from IBM. 

The OMF document is based on a document produced by the Tools Inter¬ 
face Standards (TIS) committee, made up of representatives from Borland, 
IBM, Intel, Lotus, Meta Ware, Microsoft, The Santa Cruz Operation, and 
WATCOM. The committee publishes specifications for file formats that are 
portable across leading industry operating systems. The specifications are 
available on request from Intel to tools and operating systems developers, 
and set standards they can use as a starting point in designing their projects. 

The specifications have flexibilities built in them so that developers can 
add some enhancements of their own. The IBM OS/2 16/32-bit OBJECT 
Module Format and Linear executable Module Format (LX) document is a 
superset of the TIS specifications we mentioned in the last paragraph. The 
IBM adaptation of these specifications is reproduced with permission in the 
Appendix. 


1.4 Let’s Take a Look Inside SMPl.OBJ 

Figure 1.3 is a hexadecimal dump of SMP1. OBJ that was produced when we 
compiled SMP1. C using the IBM C Set++ compiler. We used the DECODE. EXE 
program to produce this listing. 


DECODE. EXE is included on the accompanying diskette. The source 
and makefile are also included so you can modify it for your own 
needs. You might want to change the default command line options 
or output format to suit your own needs. As with the samples, we 
used only standard ANSI C functions in order to make DECODE. EXE 
easier to port to a different compiler. If you prefer, you can use any 
similar program capable of printing a binary file to look at the files 
and your results should be about the same. 
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To use DECODE. EXE on SMP1 .OBJ, make sure DECODE. EXE is located in a 
directory in your PATH and type 


decode smpl.obj /d 


in the directory containing the SMP1.0BJ file. The /d causes DECODE.EXE 
to generate the dump file, SMP1. DMP. There is another option, the /S option, 
which will send output to the screen. If you use the /D, you will be able to 
review the output more than once, whereas the /S output is not saved. You 
can use both options at the same time. 

The DECODE tool generates two files: SMP1. REC and SMP1. DMP. SMP1. DMP 
is a combined binary and ASCII dump of the records contained in the . OBJ 
file, and SMP1. REC is a record-by-record dump. Running DECODE. EXE with 
no options produces only the . REC file. In a little while we’ll look at 
SMP1. REC, but first let’s take a peek at SMP1. DMP, which was created when 
we ran DECODE. EXE with the /D option. If you look at SMP1. DMP with your 
favorite text editor, you should see the data as in Figure 1.3. 

DECODE. EXE automatically creates two sections in the file. The first is a 
strict binary dump, and the second is the same data dumped in such a way 
that any printable ASCII character is printed and non-printable characters 
are replaced by “.. ”. 

The . DMP file is difficult to interpret, but can be used if you have a need 
to look at the entire file. The . REC file produces a record-by-record format 
which should prove easier to understand. Figure 1.4 is shorter and easier 
to read. It is a printout of the first four records of SMP1.0BJ as they are 
shown in SMP1.REC. This is the default output file and is produced every 
time DECODE. EXE is run whether you use the /D or /S option or not. We will 
use this information to start looking at how the SMP1. OBJ file is made up. 

Let’s look at a couple of things about Figure 1.4 before we get too far 
into this. First, the six numbers at the left in each line represent the offset 
from the beginning of the file. Next, the 1-byte groups of data (the rest of 
the numbers in each line) are the actual data in the records. Each record is 
printed twice, in the same format as the . DMP file: hexadecimal then ASCII 
with unprintable characters represented by “. . ”. 

There is a line of dashes between each record as a separator. This format 
should make reading the listings easier as we go through this chapter as well 
as when you are examining the output of larger . OBJ files. 

Some binary file display programs display the data in a format where the 
bytes are displayed in what would appear to be reverse order. Actually, they 
represent the way the data is stored in memory, with the least significant 
byte having the lowest (closest to 0) actual memory address. For example, 
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000000 

80 

08 

00 

06 

53 

4d 

50 

31 

2e 

43 

00 

88 

Od 

00 

40 

9f 

000016 

6f 

73 

32 

33 

38 

36 

2e 

6c 

69 

62 

00 

88 

Oe 

00 

40 

9f 

000032 

64 

64 

65 

34 

73 

62 

73 

2e 

6c 

69 

62 

00 

96 

33 

00 

06 

000048 

43 

4f 

44 

45 

33 

32 

06 

44 

41 

54 

41 

33 

32 

07 

43 

4f 

000064 

4e 

53 

54 

33 

32 

04 

43 

4f 

44 

45 

04 

44 

41 

54 

41 

05 

000080 

43 

4f 

4e 

53 

54 

06 

44 

47 

52 

4f 

55 

50 

04 

46 

4c 

41 

000096 

54 

00 

99 

09 

00 

a9 

lc 

00 

00 

00 

01 

04 

00 
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FIGURE 1.3 
SMP1.DMP 


12 34 would display as 34 12. This can be confusing, but DECODE.EXE 
takes care of that for you by displaying the data in the order in which you 
would be interested in it. Figure 1.4 is a dump of SMP1. REC. The first five 
lines represent the first record in SMP1. OBJ. Let’s take a closer look. 
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/. OBJECT (.OBJ) FILES 
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FIGURE 1.4 

Record-by-Record dump of SMPl.OBJ as displayed in SMP1.REC 
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The 000000 represents the offset from the beginning of the file and 80 08 
are the first two bytes of data. Reading the information in these files takes a 
little getting used to, but with practice, it gets easier. 

NOTE: Although the OMF document gives complete details on each record 
type, we will not do that here. We have included enough detail so that you 
should be able to understand and move forward. If you feel you need more, 
you can refer to the Appendix. 

The OMF document says that the THEADR record has the following 
format: 


ID = 80 (1 byte) 

Record Length (2 bytes) 

String Length (1 byte) 

Name String (variable length based on Record Length) 

Check Sum (1 Byte) 

This means that the first thing we should find is an 80 (the ID) to mark 
the beginning of the . OBJ module. To and behold, we have an 80 in the first 
byte of the very first record. So, because we found an 80, this is a valid . OBJ 
module and the THEADR record that begins all valid . OB J modules. 

Next, we should have two bytes for the record length. The next two bytes 
are 08 00. This might make you think the record length is 0800, but you 
are thrown a little curve here. When the Record Fength field is stored in the 
.OBJ file, it is stored with the low order byte (00) and the high order byte 
(08) reversed. When DECODE. EXE reads it in, it reverses the bytes again. 
So the value is really 0008. Note that the record length does not include 
the ID byte or the 2-byte Record Fength field. DECODE. EXE takes this into 
consideration and gives us a length of 11 bytes, which is the actual total 
length of the record. 

Next is the string length, 06 bytes. This means there is a character 
string of six bytes following this field. If you take a look at the six bytes 
(53 4d 50 31 2e 43) that follow the string length field, this is a hexadec¬ 
imal representation of the string in question. If you cheat and look at the 
ASCII decode on the second line, you will see that this really says SMP1. C, 
which is the name of our source file. Our check sum is 00. As the record 
layout indicates the check sum is the last byte of the record. The check 
sum field can either be 00, as in our case, or some value that can be used to 
validate the record. 

So we have now been through the first record in the .OBJ module. It is 
a THEADR record, as advertised, and contains the name of our source file. It 
takes up the first 11 bytes of the file (eight record length, one byte for the ID 
field and two bytes for the Record Fength field). Now let’s move on to the 
second record. 
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1. OBJECT (.OBJ) FILES 


Record # 2 Record Type = COMENT 

Offset = 11 Length = 16 

000011 88 Od 00 40 9f 4f 53 32 33 38 36 2e 4c 49 42 00 
000011 . @ . . 0 S 2 3 8 6 . LIB.. 


ID = 88 (COMENT Record) 

OdOO = Length 13 (Bytes are reversed + 3 for 
ID + length = 16) 

40 = Comment Type 

9f = Comment Class (Library indicator) 
OS2386.LIB = Commentary Byte String 
00 Chk Sum 


This is a COMENT record that identifies a library file name (9f Comment 
Class - Library Indicator), in this case the OS2386. LIB import library. This 
record was placed here by the compiler as the default library to use when we 
link this object module to produce the final executable. 

As we noted in Figure 1.2, there are many variations of the COMENT record 
type. Each one means something a little different to the linker. The text 
string in a comment record can represent a symbol, some binary coded in¬ 
formation or just a plain text comment. The class/subtype determines what 
the information is and what the linker does with the record. In this case, the 
comment class field tells us that we are looking at a Library Indicator. 

Decoding the rest of the file is simply repeating the same procedure over 
and over again until we get to a MODEND (8B) record. In our sample, the 
M0DEND record begins at offset 277 and it has: 


8b 02 00 81 00 


The record type is 8b, the count field is 00 02. The 81 is the Module Type 
byte, and the last 00 is the check sum for this record. 

The information in the module type byte tells whether this module contains 
a mai n () routine or a start address. In our case the 8 indicates this module is 
a mai n () module. If this were a start address module, additional information 
would be present to define the beginning and end of descriptive data. For 
complete details of this or any record type, refer to the Appendix. 
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1.5 What Have We Learned? 

Decoding .OBJs record by record can be a very tedious process, as you 
can see. Rather than forcing you to go through the entire .OBJ file record 
by record, we have done it for you. Figure 1.5 lists the records in the file 
in correct order. If you use DECODE. EXE, it will decode the .OBJs for you. 
DECODE. EXE can also be used to inspect library files, we’ll talk more about 
them later. 


A Word About DECODE. EXE 

DECODE. EXE was written solely for instructional purposes to go along 
with this book. It works very well on the samples provided and on 
other 16-bit and 32-bit .OBJ files we have tested. It also works well 
on the .LIB files we will build later. If you use it with larger .LIB 
files such as those provided in the OS/2 Toolkit or with C Compilers, 
it will run, but it will take a long time and produce very large output 
files. We have put a couple of options into the . LIB decode portion 
to allow selection of key record types that will help you decode a 
. LIB file faster. We’ll discuss this in later chapters. 


Now back to our look at SMP1. OB J. Fortunately, most of us rarely have to 
do this type of analysis. The linker will do it all and more for us. Compiler 
designers are concerned with the information in .OBJ files. They use it 
to verify and debug the .OBJs created by their compilers. The format and 
record content must be correct when the . OB J is read by the linker in order to 
produce valid executables. Operating system designers use this same .OBJ 
record information to design the linkers and loaders that create and load 
executable programs into the system. Tools writers need this information to 
ensure their tools will work properly in the intended environment. 

The focus of this chapter has been to give you a feel for what happens when 
your source code first enters into the process that ends up with an executable 
program. It is beyond the scope of this book to go into detail on every type 
of record you might come across. You will rarely need to analyze an .OBJ 
file this closely, but it’s nice to know that it can be done. 

Experiment 

Run DECODE. EXE against SMP1.0BJ and look at all the records in 
SMP1. REC. We don’t expect you to be able to understand each and 
every record, but, looking at the record types in Figure 1.2, and the 
ASCII printout of the records from SMP1. REC, see if you can guess 
what information they are probably supplying to the linker. If you 
are really curious, consult the Appendix. 
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Record # 

RECORD TYPE 

LENGTH 

OFFSET 

FROM BEGINNING 

1 

80H THEADR 

11 

0 


2 

88H COMENT 

16 

11 

(Library 

Indicator) 

3 

88H COMENT 

17 

27 

(Library 

Indicator) 

4 

96H LNAMES 

54 

44 


5 

99H SEGDEF 

09 

98 


6 

99H SEGDEF 

12 

110 


7 

99H SEGDEF 

12 

122 


8 

9AH GRPDEF 

05 

134 


9 

9AH GRPDEF 

09 

139 


10 

9DH FIXUPP 

13 

148 


11 

91H PUBDEF 

16 

161 


12 

8CH EXTDEF 

28 

177 


13 

88H COMENT 

07 

205 

(Link Pass 2 
records) 

14 

A1H LEDATA 

16 

212 


15 

A1H LEDATA 

34 

228 


16 

9DH FIXUPP 

15 

262 


17 

8BH MODEND 

05 

277 



FIGURE 1.5 

List of Records in SMPl.OBJ 


1.6 Summary 

® Source files are turned into object files (. 0B3) by compilers and as¬ 
semblers. 

• The . OBJ s are made up of a defined set of record types, each of which 
conveys a different piece of information to the linker. 

• It is possible, but difficult, to peek inside .OBJ files using dump 
programs and examine their makeup. 

• This information is mostly useful to designers and developers, but 
can be of use to others, such as support personnel, too. 

• There is documentation available from vendors that gives details 
about .OBJ formats. 

• DECODE. EXE can be used to examine the contents of ,OBJs created 
by any compiler or assembler that conforms to the TIS standard. 

Now let’s move on to the next chapter, where we will take a look at library 
files. 
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Library (.LIB) Files 


Now that you know something about . OBJ files, let’s talk about library files. 
Library (. LIB) files contain or point to executable functions that have already 
been written and (hopefully) thoroughly tested. When we write the source 
code for our programs, we can call (name) these functions as tasks we want 
to use in our program. For example, if we want to output information to the 
screen, we can call the pri ntf function that resides in the standard libraries 
that come with all C compilers. When we later process our .OBJs with the 
linker, the linker will make sure our program knows where the code for the 
functions is, with help from the libraries. The linker does this by either 
copying the functions (such as pri ntf) into our executable or by putting in 
a pointer to the Dynamic Link Library containing the function. 

After you have written your source and compiled it into .OBJ files, the 
next step is to link all your .OBJ files together to create your executable or 
Dynamic Link Library. To do this, you have to also use one or more . LIB 
files to help resolve (locate) all the functions and data you will need to make 
the executable run. We’ll spend some time in this chapter taking a look at 
how these . LIB files are made up and how they work for you. 

All the samples in this book are on the included diskette. They were written 
using standard ANSI C functions and should therefore be easy to port to any 
compiler. The executables on the diskette were created with the IBM C 
Set++ compiler and libraries. As we said in Chapter 1, we have included 
the source as well as the executables and makefiles so you can experiment 
and try different values to see how the results change. We have tried to use 
samples that are simple enough to understand yet get the message across. 
There is a lot to see and learn by taking the time to work with them. 

In the last chapter, we introduced you to DECODE. EXE and explained that it 
is a tool that can be used to examine . OBJ and . LIB files. We also mentioned 
that it will work on all .OBJs and . LIBs, but that it was specifically written 
to use with the small samples in this book. Larger libraries, such as those 
included with the compiler or Toolkit, will take a longer time to decode than 
our samples. We have included several options when decoding .LIB files 
that will only print selected records and allow DECODE. EXE to run faster. 


15 



16 


2 LIBRARY (.LIB) FILES 


The diskette includes the source for DECODE. EXE, and it should be an easy 
matter to modify it to suit your needs and allow any record selection you 
want. Feel free to experiment. We recommend that you build each of the 
samples and run DECODE. EXE on the files produced. See if you can explain 
what you see. Taking the time to do so will help reinforce the things you 
learn here. 


2.1 Static Libraries versus Import Libraries 


We will look at two different types of libraries: static libraries and import 
libraries. A static library contains the actual code to execute the functions 
your program calls. When you run the linker and specify a static library in 
response to the “Li brari es [Jib] ” prompt, the linker gets a copy of the 
code for the function from the library file and copies it into your executable. 
Later, when you run your executable and load your program into memory to 
execute it, the code for the function is actually a part of the physical hie that 
the loader loads and runs. 

An import library, on the other hand, does not actually contain the code for 
the functions your program calls. Instead, an import library has references to 
Dynamic Link Libraries (DLLs). The references are created when the import 
library is built using a utility named IMPLIB. EXE. We will learn more about 
IMPLIB.EXE later. Import libraries and DLLs go hand in hand, as we will 
see when we go through the samples in this chapter. 

DLLs contain the actual code that makes your function do what you want 
it to do. When you link your program and specify an import library, the 
linker puts information in the executable that will tell the program where (in 
which DLL) to find the function. This information will be used by the loader 
to locate and load the proper DLLs when your program is run. We’ll take a 
closer look at the format of the executable in Chapters 4 and 5. 

Your program should run the same whether the code for the functions is in 
the executable or in a DLL. The big difference is that the executable will be 
smaller if the code is in a DLL, which results in a savings of valuable disk 
space. There are a couple of other good reasons to create import libraries 
and DLLs that we’ll discuss when we learn about the IMPLIB utility. 



2.2. HOW ARE LIBRARIES USED? 


17 


22 How are Libraries Used? 

You use either type of library in essentially the same way. When you link 
your program, one of the parameters passed to the linker is which library or 
libraries you intend to use. You can enter the library names without concern 
as to whether they are import libraries or static libraries. The linker is smart 
enough to know which is which and puts a copy of the function into your 
executable (static) or puts a DLL reference instead (dynamic). Of course you 
should know which type of linking you intend to use, but the point is that 
the link step is the same whether you are statically linking or dynamically 
linking. If your executable program will be expected to run in an environment 
that does not contain the DLLs associated with your functions, then you will 
want to use static linking. 

Compilers such as IBM C Set++ provide a set of libraries of functions that 
the programmer can use in his/her program. C Set++ provides both import 
libraries and static libraries so the programmer can write the program and 
link either statically or dynamically depending on the needs of the program 
under development. 

If you have C Set++ installed, take a look in the IBMCPP\LIB directory. 
The libraries shown provide access to the C functions the compiler package 
provides, such old favorites as pri ntf, getchar and so on. About half of 
these libraries, those whose file name looks like xxxxxI.LIB, are import 
libraries, and the rest are static libraries. The “I” as the last letter is the 
naming convention used by the IBM compiler developers to indicate an 
import library. The import libraries contain references to C runtime functions 
that are in the DLLs in the IBMCPP\DLL directory. When writing your source 
code, simply put the function name where you want to call it, and when the 
.OBJ is created, as we saw previously, there will be a reference in the .OBJ 
to each of the functions you will need. When you link the .OBJs together 
to create the running program, the linker will provide either the code to do 
the function or a pointer (import reference) to the DLL containing the code. 
Which one the linker uses depends on which type of library you specify when 
you link. 


23 How are Libraries Created? 

There are two utilities available to help the programmer create libraries. 
The LIB. EXE utility is included as part of both IBM C Set++ and the OS/2 
Warp Toolkit. LIB. EXE is used to manage both static and import libraries. 
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2. LIBRARY (.LIB) FILES 


LIB. EXE can do just about anything with . LIB files except create an import 
library. For that, you need the import library utility (IMPLIB. EXE) which is 
one of the utilities provided in the OS/2 Toolkit. We’ll get into detail about 
IMPLIB. EXE later, but for now we’ll take a brief look at how LIB. EXE works 
and see what it can do for us. 

Let’s create a tiny . LIB file and take a closer look at how it works. We’ll 
use a very simple function and put it in a static library. Later on, we’ll 
put the same function into a .DLL, create an import library, and do some 
comparisons. 

The RECUR function in Figure 2.1 is a simple demonstration of function 
recursion. Remember the object here is to teach you how things work, not 
how to code. Figure 2.1 lists all the source for SMP2 and Figure 2.2 lists the 
makefile. 

With this sample, and with following samples, we have included not only 
the source code, but also makefiles, in this case SMP2 . MAK. These makefiles 
will build the samples for you, including creating automatic response files 
for the linker and other programs. You can use the NMAKE utility, provided 
with the Toolkit, to simplify building the samples. See the Online Toolkit 
reference for details on using NMAKE, or an excellent book on NMAKE titled 
Mastering MAKE , by Tondo, Nathanson, and Yount, published by Prentice 
Hall. 

If you want to experiment a little and decide to run the individual utilities 
such as IMPLIB. EXE or LIB . EXE directly, and not use NMAKE, you can get the 
proper command line arguments and responses from the individual makefiles. 

Assuming your PATH environment variable is set up correctly, the com¬ 
mand to build SMP2 is 

nmake -f smp2.mak 

in a directory where the SMP2 source has been placed. 

NOTE: If you build any of the samples provided, we suggest you run: 

nmake -f smpX.mak clean 

first. This will erase unnecessary files from the directory. 

The makefile, as you will notice, compiles this with: 

icc -c recur.c 

(Create . OBJ but do not call the linker.) 

This should produce RECUR.OBI. You can take a look at the .OBJ using 
the skills you learned in the last chapter. You will also notice that we use 
the LIB utility (LIB. EXE) to build the SMP2LIB. LIB file. Details for running 
LIB. EXE as well as the other programs used are in the online information 
provided with the OS/2 Toolkit and C Set++. 
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/* Sample function to be added to library */ 

extern int level; 
void recurfint n) 

{ 

printf("Down recursion level %ld, n = %ld is pushed on 
"stack at &n = %u\n", 1evel++,n,&n); 

if (n) 

recur(n-l); 


printf("Up recursion level %ld, n = %ld is popped from " 
"stack at &n = %u\n", --level,n,&n); 

return; 

} 

/*-*/ 

int level = 1; 


void main(void) 

{ 

int limit; /* num of recursions, goes on stack */ 
void recur(); /* function declaration */ 

printf("Enter the number of recursions \n"); 
scanf("%d", &limit); 

recur(limit-1); 

printf("Done\n"); 

} 

/* - */ 

FIGURE 2.1 
SMP2 Source. 


LIB. EXE creates our library for us. After you run the makefile, if you 
do a DIR of the directory, you should see the SMP2LIB.LIB as well as a 
SMP2LIB.0UT file. You can look at SM2LIB.0UT with your favorite text 
editor and see that RECUR has been added to your library. You will see 
some other external definitions there, too. These are necessary “overhead” 
functions that your program will need to run in the OS/2 environment. 

The makefile also creates SMP2. EXE. You should notice that the make¬ 
file uses inline response files to provide input to LIB.EXE and the linker, 
LINKB86. EXE but these input files are not kept. A module definition file, 
SMP2 . DEF is also created but it is retained in the same directory. You can 
take a look at it with your favorite editor. 

One of the fields in the inline response file that is input to the linker is 
SMP2LIB. LIB. When LINK386. EXE reads this input, it will determine that 
SMP2LIB. LIB is one of the libraries (in addition to the defaults) you want 
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# 

# Simple Makefile to build SMP2.EXE using IBM C Set++ compiler. 

# 

# The OS/2 Warp Toolkit for Software Developers 

# Copyright (c) 1995. Prentice Hall. 

# 

# 

# Define Suffix Rules 

# 

.SUFFIXES: 

.SUFFIXES: .c .obj .lib .exe 
# 

# Define Macro Information 

# 

EXEC = smp2.exe 

LIBC = lib 

LIBR = smp21ib. 1 i b 

CC = icc 

LINK = 1ink386 


# 

# Define inference Rules 

# 

.c.obj: 

$(CC) -c $*.c 

# 

# Define Pseudotarget 

# 

all: S(LIBR) $(EXEC) 

# 

# Create the library 

# 

S(LIBR): recur.obj 

( if exist S(LIBR) del S(LIBR) ) 
S (LIBC) @«$ (@B) . rsp 
S(LIBR) 

y 

+recur.obj 
S(LIBR:.lib=.out) 

«nokeep 

FIGURE 22 
SMP2.MAK 
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# 

# Create the executable 

# 

S(EXEC): $(EXEC:.exe=.obj) $(EXEC:.exe=.def) S(LIBR) 
S(LINK) @«$ (@B) 

S(EXEC:.exe=.obj) 

$@ 

nul 

S(LIBR) 

$(EXEC:.exe=.def) 

«nokeep 

# 

# Create the module definition file for SMP2 

# 

$(EXEC:.exe=.def): 

©echo $@ @«$@ 


SMP2.DEF - Library Sample Module Definition File 


NAME SMP2 WINDOWCOMPAT 

DESCRIPTION ’OS/2 32-bit EXE - using libraries’ 
PROTMODE 
«keep 
# 

# Remove unneeded files 

# 

clean: 

-del *.obj *.lib *.def *.out *.exe 

FIGURE 2.2 (continued) 

SMP2.MAK 
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2. LIBRARY (.LIB) FILES 


to link with. The linker will determine that SMP2LIB. LIB is a static library, 
find the code for RECUR and put a copy of it into SMP2 . EXE. 

You can also run DECODE.EXE against SMP2LIB.LIB and take a look at 
the output produced. SMP2LIB.REC will detail the contents of the file. You 
should find the references to the RECUR function as well as the compiler¬ 
generated default library names and more. 

As an experiment, you can compile SMP2.C from the command line using: 

icc smp2.c 

This time, leave out the option (-c) which tells the compiler to create only 
an .OBJ file. Leaving this option out tells the compiler to call the linker 
automatically and try to create the executable program. You should get the 
message: 


L2029 ’recur 5 Unresolved External 

from the linker. This is telling you that the linker knows you want the RECUR 
function, but doesn’t know where to find it. 

This is remedied by simply relinking SMP2.0BJ and specifying the 
SMP2LIB. LIB library at the Libraries: prompt. Now when the linker looks 
for the RECUR object code, SMP2LIB. LIB will tell the linker where it is. The 
linker can now get a copy of the code from the library and put it into the 
executable, and we no longer get the “unresolved” message, as the linker 
was able to resolve the reference. 

You can try this program out by entering the name of the program, SMP2. 
The program will ask for the number of recursions you want it to run. You 
can enter any number, but we recommend a number less than 10, which 
should be sufficient for you to get the idea. The program passes the number 
of recursions to the RECUR function which recursively calls itself. 

So, what have we done here? We created our function (RECUR), put it into 
a library (SMP2LIB. LIB) and built a little program that called the function 
from the library. This is a very simple example of how to create and use a 
static library. The linker put the code for the function into our executable, 
and we now have an executable that will run all by itself. Later, we’ll put 
our function into a Dynamic Link Library and see the difference. 

This gives you a pretty good idea of how a static library is created and 
how the linker is used to locate our functions for us and put them into our 
executable. Most libraries are far more complex than our example, but the 
principle remains the same no matter how sophisticated the program or the 
library. 
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2,4 What else can LIB,EXE do for you? 

The online documentation for WorkFrame/2 gives details on the full ca¬ 
pabilities of LIB. EXE. You can use it not only to create libraries, but to add, 
replace and copy object modules to and from the library files. So as you write 
useful functions, you can put them into your own libraries and use them in 
other programs. 

You can try an experiment by running LIB .EXE against SMP2LIB.LIB. 
When it asks you for the operation, reply “-recur.” This tells LIB to re¬ 
move the RECUR function from the library and create another library exactly 
like SMP2LIB. LIB but not containing our RECUR function. Try it, naming 
the new library something like NEWLIB. LIB. Then run DECODE. EXE against 
each of the . LIB files and compare the contents of the SMP2LIB. REC and 
NEWLIB. REC. You should see that the RECUR function has been removed from 
NEWLIB.LIB. 

The list function of LIB. EXE can be valuable in several situations. The 
OS/2 Toolkit provides two import libraries, OS2286.LIB and OS2386.LIB.In 
the early days of OS/2 development, there were a lot of errors and omissions 
in these libraries. Because some functions were referenced in only one library 
and not the other, and because they were sometimes named differently in each 
library, it was very useful to create a list file of each library and scan the list 
files with a text editor to make sure you were using the right library and 
calling the right function in your link process. 

This is a good technique for today’s OS/2 because some functions are 
only implemented as 16-bit functions while most are 32-bit, and the naming 
conventions are sometimes confusing. Any program, 16-bit or 32-bit, can 
get to any function provided you know the correct name of the function you 
want and link with the correct library. 

The above procedure can also be used to debug libraries other people have 
created. It has solved many “unresolved external” problems. So it’s nice to 
be able to figure out exactly what the function is called in the library you are 
linking with. 

The LIB. EXE that is in the current version of WorkFrame is much more 
sophisticated than prior versions. One of the nice features is that, based 
on command line arguments, you can produce three different listings, each 
with a different level of detail. If you experimented with LIB. EXE and tried 
removing the RECUR function as suggested above, let LIB. EXE create a couple 
of listings of each library and compare the difference. You should find that 
one library contains RECUR, while the other does not. 
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2o5 Import Libraries 

What about the other type of libraries, import libraries? As mentioned 
previously, import libraries don’t contain any executable code, only refer¬ 
ences to functions in Dynamic Link Libraries (DLLs). Let’s take a look at 
what import libraries do for us. 

Import libraries are used to get to the functions in DLLs. But do we really 
need to use them? There are other ways of accomplishing the same thing 
without import libraries. When a DLL is created, we use text files called 
Module Definition Files to define properties of the functions contained in the 
DLL and to identify which functions are to be exported (made available to 
other programs or their DLLs). These Module Definition Files are supplied 
as input to the linker as we create our DLL. The linker creates records in 
the .DLL file that identify the functions and define which are available to the 
outside world (exported). More on this later in Chapter 4. 

When we link our program, we can use Module Definition Files to tell 
the linker which functions in which DLLs our program will use (import). 
The linker will provide appropriate records, this time in our main program 
executable (. EXE), that will cause the correct DLLs to be loaded when we 
run our program. 

So why should we use an import library? It is an extra step, but in the long 
run, it will make your life much easier. You can create a DLL and a matching 
import library and give the library and DLL as a set to anyone else who needs 
to access the functions contained in your DLL. That way, there is no worry 
about creating Module Definition Files to get at the functions; they simply 
link with the import library and let the linker resolve the external references 
to DLL functions. Therefore, we recommend you do take the time to build 
import libraries. 

With the OS/2 Toolkit or IBM C Set++, this is exactly what IBM did. 
They created the DLLs and provided you with the import libraries to get at 
the functions in them. Of course, the compiler also provides static libraries. 


2,6 Petting oer Function in a DLL 

Making an import library is a fairly painless process. You use the same 
module definition file (.DEF) that you used to create the DLL. You simply 
input that very same module definition file to IMPLIB. EXE and out comes 
your import library. Since you already created the , DEF file, you don’t have 



2.7. LINKING TO A DLL WITHOUT AN IMPORT LIBRARY 


25 


to create another; simply use your existing one. You then have a library file 
that resolves references to functions contained in your DLL. 

Figure 2.3 is the makefile for SMP3. SMP3 is the same as SMP2 with the 
exception that this time we put the RECUR function into a DLL and created an 
import library (SMP3LIB. LIB). Notice that the makefile creates (and keeps) 
two Module Definition Files, one for SMP3 . EXE and one for SMP3DLL. DLL. 
We use the same Module Definition file to create both the import library, 
(verb+SMP3LIB.LIB+) and the DLL. 

The details of the entries in Module Definition Files are in the online 
documentation provided with the linker, so we’ll leave it up to you to look 
at it if you want more information. Basically, this file (SMP3 . DEF) tells the 
linker that we are creating a Dynamic Link Library and that we are exporting 
a function (RECUR). What that means is that any program that wants to use 
RECUR can do so by dynamically linking to this DLL. In this sample, we 
provide that capability by creating SMP3LIB.LIB using the IMPLIB utility 
and the Module Definition File we used to create the DLL. When we link 
SMP3 .OBJ, we add SMP3LIB (see SMP3.MAK) to the list of default libraries, 
and the linker is able to find our code. 

Notice that SMP3 . EXE is slightly smaller than SMP2 . EXE. This is because 
we don’t carry the code for RECUR in the executable. If you have DLLs that 
are accessed by multiple program executables, you can imagine the savings 
in valuable disk space. 


Are we Really Using the DLL? 

If you would like to try an experiment, rename SMP3DLL.DLL to 
something like SMP3DLL. XXX and then try to run the program. What 
you will see is that the loader knows it needs SMP3DLL.DLL and 
can’t find it. As we will learn later, the executable contains records 
that indicate which DLLs it needs. In this case, the loader knows 
it needs SMP3DLL.DLL, can’t find it and generates the error mes¬ 
sage. After you experiment, make sure you rename SMP3DLL. XXX to 
SMP3DLL.DLL. 


2o7 Linking to a DLL Without an Import Library 

SMP4 also builds a DLL, but this time, we don’t build the . LIB file. Instead, 
if you take a look at the two Module Definition Files (SMP4. DEF for the . EXE 
and SMP4D. DEF for the DLL), you will see that the DLL exports the RECUR 
function while the . EXE imports it. What that means is that SMP4.DLL makes 
the function available (exports it) and SMP4. EXE wants to use it (imports it). 
The real difference here is that when we build the . EXE we use SMP4. DEF 
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# 

# Simple Makefile to build SMP3.EXE using IBM C Set++ compiler. 

# 

# The OS/2 Warp Toolkit for Software Developers 

# Copyright (c) 1995. Prentice Hall. 

# # Define Suffix Rules # 

.SUFFIXES: 

.SUFFIXES: .c .obj .dll .exe 

# 

# Define Macro Information 

# 

EXEC = smp3.exe 

DLL = smp3dl1.dl1 

LIBR = smp31ib. 1 i b 

LIBS = dde4sbso 

IMP = implib 

CC = icc 

LINK = 1ink386 

LFLAGS = /noe 

# 

# Define Pseudotarget 

# 

all: $(DLL) S(EXEC) 

# 

# Create the DLL - SMP3DLL 

# 

S(DLL): recur.obj $(DLL:.dl1=.def) 

$ (LINK) @«$ (@B) . 1 nk 
recur.obj 
$@ 
nul 

S(LFLAGS) 

$(DLL:.dl1=.def) 

«nokeep 

S(IMP) $(LIBR) $(DLL:,dll = .def) 

FIGURE 2.3 
SMP3.MAK 
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# 

# Create the executable 

# 

S(EXEC): smp3.obj $(EXECexe=.def) $(LIBR) 

S(LINK) @«$(@B) .Ink 
smp3.obj 
$@ 
nul 

S(LIBR) $(LIBS) $(LFLAGS) 

$(EXEC:.exe=.def) 

«nokeep 

# 

# Create the module definition file for SMP3DLL 

# 

$(DLL:.dl1=.def): 
echo $@ @«$@ 


SMP3DLL.DEF - DLL Sample program dynamic linking library definition file 


LIBRARY SMP3DLL 

DESCRIPTION ’OS/2 32-bit DLL - Simple DLL’ 

PROTMODE 

EXPORTS 

recur 

«keep 

FIGURE 2.3 (continued) 

SMP3.MAK 
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# 

# Create the module definition file for SMP3 

# 

S(EXEC:.exe=.def): 
echo $@ @«$@ 


SMP3.DEF - Executable module definition file 


NAME SMP3 WINDOWCOMPAT 

DESCRIPTION ’OS/2 32-bit EXE - calls a DLL’ 
PROTMODE 
«keep 
# 

# Create the recur object module 

# 

recur.obj: recur.c 

$(CC) -c -Ge- recur.c 


# 

# Create the smp3 object module 

# 

smp3.obj: smp3.c 

$(CC) -c -Ge+ smp3.c 

# 

# Remove un-needed files 

# 

clean: 

-del *.obj *.dll *.def *.lib *.exe 


FIGURE 2.3 (continued) 
SMP3.MAK 
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instead of an import library to tell the linker that our program is importing 
RECUR from the SMP4DLL.DLL as noted on the IMPORTS statement in the 
SMP4. DEF file. See the statements that are echoed into SMP4. LNK, the linker 
response file, and compare them with the previous sample. This shows a 
way you can build a DLL without an import library. 

Although this works, it is still preferable to use an import library as we 
mentioned previously. Also notice that this sample required the use of a 
second Module Definition File to tell the linker that SMP4. EXE is to import 
the RECUR function. 

Figure 2.4 shows the overall flow of the files and tools used to create 
SMP4. Note that SMP4.0BJ is our main routine and therefore is input to the 
linker when we are creating SMP4.EXE and that our function (RECUR.OB J) 
is in the Dynamic Link Library, SMP4DLL.DLL. Also note that by using 
SMP4.DEF and SMP4D.DEF, we eliminate the need for an import library. 


2.8 What is the Format of a Library File? 

A library file is very similar in makeup to an .OBJ file. It contains one 
or more .OBJ modules if it is a static library and DLL references if it is an 
import library. The .OBJ modules are complete and follow each other in 
the library. A library file has a different header record that indicates that it 
is indeed a library. The .OBJ modules that it contains are almost exactly 
like those we looked at in the last chapter, with the exception that there is 
some padding added to the last record of each module to be sure that the 
next module starts on a page boundary. The page size is determined by the 
compiler and is part of the library header record. 

There is also a dictionary after the last object module that lists all the 
variables in the library. A Library End Record indicates the end of the object 
modules and the beginning of the dictionary. The Library End Record is also 
padded to ensure that the dictionary begins on a 512-byte boundary. 

If you run DECODE. EXE against SMP3LIB . LIB, you should get the overall 
picture of what a library file looks like. DECODE. EXE does not print out the 
dictionary, but it does give you everything up to the beginning of it. 

If you are really interested in learning more, there is a document, men¬ 
tioned in the last chapter, titled “Tool Interface Standards — Portable For¬ 
mats Specification,” which is published by the TIS committee; a copy of the 
document is available to developers from Intel. It also contains a section, 
Relocatable Object Module Format, which is the foundation for documents 
such as the one reproduced in the Appendix of this book. Not everybody is 
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SMP4.EXE 


recur () 


SMP4DLL.DLL 


recur () 
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interested in that level of detail, but we believe it is helpful to understand the 
inner workings of the files you use in creating running programs. 


2.9 Summary 

® There are two basic types of libraries, static and import. 

» Static linking puts a copy of the executing code into your program. 

• Dynamic linking points to the executing code in a DLL. 

• DLLs export functions and variables to other programs and DLLs. 

• Module Definition Files tell the linker whether to export or import as 
well as define the characteristics of the executable. 

• IMPLIES. EXE is used to create import libraries, while LIB. EXE is used 
to create static libraries and perform all the other library maintenance 
functions. 

• Library files are similar in makeup to .OBJ files. They contain one 
or more .OBJ files and a dictionary of symbols. 

We’ve mentioned the linker many times now. In the next chapter, we will 
talk a lot more about this very powerful program. 
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The OS/2 Linker 


LINK386. EXE is the 32-bit Linear Executable (LX) Linker, and it is provided 
with the OS/2 operating system. Its purpose is to take object files and library 
files and combine them to create the program and DLL files that OS/2 exe¬ 
cutes. It can also create OS/2 device drivers, but that is not a subject for this 
book. 

The output file from LINK386 is an executable file that is relocatable. 
This means that the addresses required to ran the program are not fixed, and 
therefore the program can be loaded and ran by OS/2 at any address the 
system has available. So it’s possible that every time you run your program, 
it will occupy different physical storage addresses. But it will still perform 
exactly the same way. 


3.1 What does LINK386 Actually do? 

Previous chapters gave you an overview of what the linker does. In Chapter 
1, we talked about how object modules (.0B3 files) are created by compilers 
and are made up of many different types of records, each of which conveys 
a specific piece of information to the linker. 

In Chapter 2, we discussed library (.LIB) files, including the differences 
between static libraries and import libraries. We said that static libraries 
contain actual function code, and import libraries contain no executable code 
but rather references to DLLs. The linker copies code from static libraries 
into our executable, but only puts references to DLLs when we use import 
libraries. 

The linker’s job is to take all of this information from the .OBJ files and 
library files, which could be a considerable amount of information, and put 
it together into a program that OS/2 can load and execute. Not a small task 
by any stretch of the imagination. 

To continue the analogy we used before, if the source code is the blueprint 
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and the object modules are the building blocks, then the linker is the skilled 
builder that puts everything together. 

The linker itself is an OS/2 executable program. As such, it can accept 
input arguments. As we saw previously, the linker takes . OBJ file names 
and options for command line arguments and issues four prompts for addi¬ 
tional information. We can enter the arguments all at once, we can create 
a response file to enter them for us, or we can simply enter LINK386 with 
no arguments and let the linker prompt us for all entries. For details, see 
the online documentation. Typing LINK386 /? will output a summary of 
options to the screen. This will serve as a good memory jogger once the user 
is familiar with LINK386. 

Figure 3.1 shows the relationship between files that are input to the linker 
and the output which is normally an executable (.EXE) file. 



FIGURE 3.1 

Linker input vs. output. 

The first additional piece of information the linker needs, in addition to the 
. OBJ names, is the name of the output file. This will either be an . EXE or a 
■ DLL. We can enter multiple . OBJ names to combine object modules into one 
executable. If we are combining more than one . OBJ file, the linker default is 
to name the executable based on the name of the first. OBJ file in the argument 
list. For example, if our command line specified SECOND. OB J , FIRST. OBJ 
and THIRD . OBJ , the linker would call our default output file SECOND . EXE . 
Bearing this in mind, we can enter the executable name we choose at the 
prompt, and the linker will oblige. 

The next thing the linker prompts us for is the name of a map ( . MAP) file. 
A map file lists all the public symbols in our executable along with their 
addresses. There are two ways of creating the . MAP file. The first is to enter 
the name of our . MAP file at the prompt or in a response file. If we do that, the 
. MAP file will contain only a list of segments. This may be fine, but in may 
cases, we would like to know where symbols are located in those segments. 

Figure 3.2 shows a . MAP file created when linking SMP2 . OBJ by entering 
the name of the file at a prompt as described in the last paragraph. Although 
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it contains quite a bit of information, you will see in a minute that there is a 
way to get even more information. 


smp2 

Start Length Name 

0001:00000000 00000737CH CODE32 
0001-.0000737C 000000030H _MSGSEG32 
0002:00000000 000000520H DATA32 
0002:00000520 000000000H CT0R_DT0R1 
0002:00000520 000000000H CT0R_DT0R2 
0002:00000520 000000000H CT0R_DT0R3 
0002:00000520 0000007E0H CONST32 
0002:00000D00 00000000CH EDC1 
0002:00000D0C 000000294H EDC2 
0002:00000FA0 000000004H EDC3 
0002:00000FA4 000000000H BSS32 
0002:00000 FA4 000000104H c_comtnon 
0002:000010B0 000008000H STACK32 


Cl ass 

CODE 32-bit 
CODE 32-bit 
DATA 32-bit 
DATA 32-bit 
DATA 32-bit 
DATA 32-bit 
CONST 32-bit 
EDC_CLASS 32-bit 
EDC_CLASS 32-bit 
EDC_CLASS 32-bit 
BSS 32-bit 
BSS 32-bit 
STACK 32-bit 


Origin Group 
0000:0 FLAT 
0002:0 DGROUP 

Program entry point at 0001:000000F8 


FIGURE 3.2 
.MAP File. 

The other way to create the . MAP hie is to start the linker with /MAP as one 
of the options. This will also produce a .MAP hie, but in this case, the hie 
will contain a lot more information about the symbols and their addresses. 
Map hie information along with OS/2 error information can be a valuable 
tool for debugging. 

Figure 3.3 shows the .MAP hie created from linking the same SMP2.OBJ, 
this time however, we used the /MAP option when we started the linker. 
Compare the information in this . MAP hie with that in Figure 3.2. This time 
we have all the information we had before, but in addition, we have a lot of 
detail about each of the functions in our program. We will not go into detail 
about this information in this chapter. As we progress to later chapters, this 
information will become more meaningful. 

The . MAP hie is also used to generate debug information for the OS/2 
kernel debugger, which we will talk about in Chapter 6 when we talk about 
MAPSYM.EXE. 

The third bit of information the linker needs to know is what library or 
libraries we wish to use. Compilers generate default library names and insert 
them into our .OBJ hies. As you may recall, the COMENT class 9F records 
we looked at in Chapter 1 contain the default library names. In most cases, 
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Start Length Name 

0001:00000000 00000737CH CODE32 
0001:0000737C 000000030H _MSGSEG32 
0002:00000000 000000520H DATA32 
0002:00000520 000000000H CT0R_DT0R1 
0002:00000520 OOOOOOOOOH CTOR_DTOR2 
0002:00000520 OOOOOOOOOH CT0R_DT0R3 
0002:00000520 0000007E0H CONST32 
0002:00000D00 00000000CH EDC1 
0002:00000D0C 000000294H EDC2 
0002:00000FA0 000000004H EDC3 
0002:00000FA4 OOOOOOOOOH BSS32 
0002:00000FA4 000000104H c_common 
0002:000010B0 000008000H STACK32 

Origin Group 
0000:0 FLAT 
0002:0 DGROUP 

Address Publics by Name 

0002:00001090 ©BSSATOF.C 

0002:OOOOOFBC OBSSATOLD.C 

0002:00001024 OBSSEDCINIT.C 

0002:OOOOOFAC OBSSGOSCAN.C 

0002:00001048 @BSSN_EXCEPT.C 

0002:00001038 OBSSPRTEMSG.C 

0001:0000288C atof 

0001:0000738E DOS32GETMESSAGE 

0000:00000000 Imp DOS32IQUERYMESSAGECP (MSG.8) 

0000:00000000 Imp DOS32TRUEGETMESSAGE (MSG.6) 

0000:00000000 Imp DosAllocMem (DOSCALLS.299) 

0000:00000000 Imp DosCreateMutexSem (DOSCALLS.331) 

0000:00000000 Imp DosExit (DOSCALLS.234) 

0000:00000000 Imp DosExitList (DOSCALLS.296) 

0000:00000000 Imp DosFreeMem (DOSCALLS.304) 

0000:00000000 Imp DosGetlnfoBiocks (DOSCALLS.312) 

0001:0000738E DosGetMessage 

0000:00000000 Imp DosQueryDBCSEnv (NLS.6) 

0000:00000000 Imp DosQueryHType (DOSCALLS.224) 

0000:00000000 Imp DosQuerySysInfo (DOSCALLS.348) 

0000:00000000 Imp DosRaiseException (DOSCALLS.356) 

0000:00000000 Imp DosRead (DOSCALLS.281) 

0000:00000000 Imp DosSetFiiePtr (DOSCALLS.256) 


Ci ass 

CODE 32-bit 
CODE 32-bit 
DATA 32-bit 
DATA 32-bit 
DATA 32-bit 
DATA 32-bit 
CONST 32-bit 
EDC_CLASS 32-bit 
EDC_CLASS 32-bit 
EDC_CLASS 32-bit 
BSS 32-bit 
BSS 32-bit 
STACK 32-bit 


FIGURE 3.3 
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0000:00000000 Imp 

0000:00000000 Imp 

0002:00001058 

0001:00000FE8 

0001:00006090 

0001:00000C6C 

0001:0000699C 

0002:00000030 

0002:00001054 

0001:00000000 

0001:0000099C 

0001:00006ED4 

0001:00004088 

0001:00000048 

0001:00005E18 

0001:0000737C 

0002:000000C8 

0002:000000C0 

0002:000000C4 

0001:00001E08 

0001:000028B4 

0001:00001E44 

0001:00002384 

0001:00001E80 

0001:00002960 

0001:00001FA8 

0001:00007014 

0001:00003E1C 

0002:000000B4 

0002:OOOOOOB8 

0001:000021AC 

0001:00002290 

0002:OOOOOFA4 

0001:000023B4 

0001:00002E40 

0001:00006EC0 

0002:0000106C 

0001:00003EF0 

0001:00001A70 

0001:00005E78 

0001:00001874 

0001:000001EO 

0002:00000510 


DosSetSignalExceptionFocus 

(DOSCALLS.378) 
DosWrite (DOSCALLS.282) 

errno 
exi t 
f flush 
free 
getenv 
1 evel 
1 i mi t 
mai n 
malloc 
mbtowc 
printf 
recur 
scanf 
sig32 
stderr 
stdin 
stdout 
strcspn 
strnicmp 
strspn 
strtod 
strtol 
strtold 
strtoul 
wcstombs 
wctomb 
_argc 
_argv 
_asciitld 
_asciitod 

_Async_exception_flag 
_atofieee 
_atold 

_bit_test_set 

_b roken_time_pt r 

_bufprint 

_cal1back_opt_sys 

_convert 

_critlib_except 

_CRT_init 

_crt_msg_hand1 e 


FIGURE 3.3 (continued) 



38 


3 . THE OS/2 LINKER 


0001:000007B0 
0002:000003F0 
0002:00001064 
0002:000004F4 
0002:00001040 
0002:000000D0 
0002:000005E0 
0002:000005D8 
0002:00000618 
0002:00000608 
0002:00000610 
0002:00001088 
0002:00000600 
0002:000005F0 
0002:000005F8 
0002:0000108C 
0002:00000FA4 
0001:00001B8C 
0002:00001020 
0002:000010B0 
0002:00001080 
0001:00001A4C 
0001:00001798 
0001:000017C8 
0002:000000B0 
0001:00001080 
0001:00001A2C 
0001:00006118 
0002:00000D00 
0002:00001060 
0001:00006360 
0001:000064EC 
0002:00000634 
0002:0000062C 
0002:00000630 
0002:00000628 
0002:00000620 
0002:00000624 
0001:000020A0 
0001:00001A48 
0001:00001AC4 
0001:00001A40 
0001:000067F0 


_CRT_term 
_ctable 
_ctype 

_ctypeModu1e 

_cvt_buf_ptr 

_daylight 

_DBL_MAX 

_DBL_MIN 

_dneginfi 

_dnegqnan 

_dnegsnan 

_doserrno 

_dposinfi 

_dposqnan 

_dpossnan 

_dttm_ptr 

_edata 

_edcGetMessage 

_edcinit_fin 

_end 

_environ 

.Exception 

.exception_dl1init 

_exception_procinit 

_exeentry 

_EXE_Exception 

_fcloseall_weak 

_filib 

_fi rstei b 

_flags 

.Flush 

_flushb 

_fnegi nfi 

.fnegqnan 

.fnegsnan 

.fposinfi 

.fposqnan 

.fpossnan 

_freeCtype 

_freeCtype.weak 

.FreeFCB 

_freeLocale.weak 
.getcx 


FIGURE 3.3 (continued) 
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0001:000017FC 
0001:00001A88 
0002:00000FDC 
0001:00000FAC 
0001:00000DE4 
0002:000005E8 
0001:00006A94 
0002:000005D0 
0001:000020BC 
0001:00001A44 
0002:00001070 
0002:00000FA0 
0002:00001044 
0002:00000642 
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these are the names of the most frequently used libraries. Compilers also 
provide options to allow us to change the defaults if we wish. 

The linker reads this library information from the . OBJ files and will link 
with these default libraries, but if we need functions from any additional 
(non-default) libraries, we have to enter them at the linker library prompt. 

There may also be occasions when we want to use other libraries in place 
of the defaults. For this the linker has an option, /NOD, standing for NO 
Default, which will cause the linker to ignore the default library records in 
the oOBJs. In this case, we must enter library names at the correct prompt, 
or none of our function calls or references will get linked and the linker will 
generate errors. 

Finally, the linker prompts us for the name of a Module Definition File. 
This is important in OS/2. If we are building a DLL, the Module Definition 
File tells the linker the DLL name, defines the segments and their properties, 
and also lists those functions contained in the DLL which are available to 
other executables (exported). 

We can also enter a Module Definition File if we are building an executable 
that needs to use (import) functions contained in a DLL and there is no 
import library associated with that DLL. Later when we look at the format 
of an executable, we will see why the information in the Module Definition 
Files is so important. Simply hitting enter (or leaving the field blank in our 
response file) tells the linker that we are building a program that doesn’t 
require a Module Definition File. 

The linker has many command line options that control how our output 
file is put together, what files are actually generated, inclusion of debug 
information, stack and heap settings and many more interesting things. We 
will discuss a few of them in this chapter, but for details on all of the options, 
we refer you to the online Toolkit information which gives complete details 
on how to run the linker as well as how to use each of the options. 


3.2 Some Interesting Options 

Most of the options for LINK386 allow the programmer to “fine tune” the 
executable to the operating system to allow it to take up less disk space or to 
run more efficiently. While compilers usually allow some code optimization, 
many of the options of the linker allow some adjustment to the way the 
executable is put together by the linker. In this section, we will talk briefly 
about a couple of them. 

There is a long form and a short form for many of these options. We 
have used the long form in the following descriptions. For details see the 
LINK386 documentation. 
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/ALIGNMENT lets you determine where each page in the executable starts. 
A value of 128, for instance, makes each page start at a multiple of 128 
bytes from the beginning of the executable file. This allows for some 
tuning to allow for variations in page size in the different operating 
systems, which can have an effect on program performance. 

/BASE amounts to a request to the Operating System to load the objects in 
this executable, starting with the first object at the address the user 
specifies and continuing with the next object at the next available 64K 
increment and so forth. The system will honor the request if possible 
and fix up addresses accordingly. If the system can’t load at the 
requested address, it will load it where it can and adjust accordingly. 
This option allows for some address space management. 

/DOSSEG causes segments to be named in a standard OS-2/DOS order. 
This conforms to standards that have been established since the early 
days of DOS. This is the same as the DOSSEG COMENT Class 9E men¬ 
tioned in Chapter 1. Many compilers insert the DOSSEG COMENT into 
the .OBJ, therefore this option is not usually necessary. 

/EXEPACK causes repeated patterns of bytes to be stored in the executable 
in a compressed mode. This is called iterated data, and we will 
discuss it again in the next chapter when we talk about . EXE format. 
Using this option makes the executable smaller and ends up saving 
disk space. 

/INFORMATION is an interesting option to use. It gives you information 
about which files are being linked, which libraries are being used and 
which functions in those libraries are being referenced. This option 
allows us to watch the link process progress and if any errors are 
occurring, may help to identify at what point in that process they 
occur and what file or files may be causing them. 

/MAP causes the linker to generate a detailed . MAP file, as we mentioned 
earlier. This version of the . MAP file contains lists of symbols and 
their addresses as well as segment information. It is also used as 
input to the MAPSYM utility that creates files for the kernel debugger. 

/NOEXTDICTIONARY tells the linker not to search the extended dictio¬ 
nary. The extended dictionary is an optional list of symbols put in 
a .LIB file by the library utility (LIB. EXE). It helps to speed the 
linking process. This option will eliminate that search, but the link 
process will be slower. Eliminating the extended dictionary search 
can be helpful when symbols get redefined, which causes the linker 
to generate errors. 
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/PACKCODE and /PACKBATA can be used to speed up your program and 
also make it a little smaller. /PACKC and /PACKD take code segments 
and data segments respectively, group them together and give them 
the same segment address. This usually makes the executable file 
smaller while speeding up execution time by minimizing the need 
to reload segment registers. You can further compact your code if 
you use the /FARCALLTRANSLATION option which replaces FAR calls 
within the same segment with NEAR calls. 


33 Which Options Should We Use? 

This is a good question; unfortunately, there is no good answer. There are 
some options that are required to build certain types of executables, such as 
DLLs for example. The documentation accompanying your compiler and the 
Toolkit will tell you how to link your programs. 

When it comes to fine tuning, though, there are no set rules. The IBM C 
Set++ compiler calls the linker with: 


/PMTYPE:VIO /NOI /ALIGN:16 /EXEPACK /BASE:65535 


as the defaults. The developers of the compiler may feel these are optimal, 
but there is absolutely nothing that says you shouldn’t experiment on your 
own. There are a lot more linker options; see the Toolkit documentation for 
further details. 

A good experiment would be to take one or more of the samples, or even 
DECODE. EXE, and link it using different values for some of these parameters 
and see what the different executables look like as far as size and/or perfor¬ 
mance. You won’t see much difference in performance, as these programs 
are small, but large applications are a different story. 


3.4 How Does The Linker Put It All Together? 

If you remember what we learned back in Chapter 1, you know that every 
object module (.OBJ) is made up of many different OMF records, each of 
which means something to the linker. When we pass these object files as 
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input to the linker for processing, the linker builds the executable that con¬ 
tains information from each and every one of these OMF records. It uses the 
information to generate various records and tables within the executable. 

The linker also builds a header (called a 32-bit Linear EXE Header or LX 
header, for short) which it appends at the beginning of our executable. This 
header contains very important information about internal table sizes and 
locations that OS/2 needs to load and run the program. (See Figure 4.1 on 
page 52.) Some of these tables are created as a direct result of the OMF records 
in our .OBJ files, as we discussed in prior chapters. You should recognize 
some of the table names and associate them with the record information we 
talked about in Chapter 1, for example, the Fixup Table, the Import Module 
Table and so forth. The LX header contains information telling the system 
where to find these tables as well as other pertinent information contained in 
the executable. 

As you also know by now, linking with a static library will cause copies of 
executable code from called library functions to be placed into the executable. 
There is a field in the LX header that contains a pointer to the offset of the 
Object Table, where these objects or pieces of executable code are located. 
We’ll talk a little more about this in the next chapter. 

There is also an Import Module Table that lists information about proce¬ 
dures the program needs that reside in DLLs (imports). The header has a field 
that points to where in the executable this table is. The loader looks at this 
table to determine which DLLs have to be loaded to run this program. 

If you have the OS/2 Toolkit, you can get detailed variable, macro and 
structure information about the LX header as well as the other standard 
header formats from a couple of files in the TOOLKIT\H directory. There you 
will find EXE. H, EXE386. H and NEWEXE. H. A browse through these files with 
a compare one against the other, text editor will reveal a wealth of interesting 
information. 

In the next chapter we will take a closer look at the LX header and the 
overall format of the . EXE/DLL file. 

This has been a very high level discussion on the linker. The linker is an 
important program, and we could spend a lot of time going over details of 
options, parameters, response files and the like. That information is available 
in the online documentation provided with the Toolkit, and we urge you to 
read it when you can. But the intent of this book is to learn a little more 
about what goes on “under the covers”, so we won’t be spending too much 
time discussing the linker here. 

Later in the book, when we take a look inside an executable file and see 
how it is put together, you should appreciate what an important job the linker 
performs and what an incredible program it really is. It has to make sure that 
every piece of information from all the source .OBJ and . LIB files as well 
as Module Definition File statements go into an exact, defined location and 
format in its output, a mind-boggling task. 
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EXEHDR.EXE 

There is a great tool available with the OS/2 Toolkit that makes most 
of the header information visible to us. This tool is EXEHDR.EXE. 
It will print out all the information you ever wanted to know about 
an executable and then some. We will talk more about it in the next 
chapter also but if you want a sample of what EXEHDR.EXE can do, 
go to the directory where you built SMP4. EXE and enter: 

exehdr smp4.exe 

at the command line. You will get output that gives you some de¬ 
tailed information about the file. This information is extracted from 
the LX header the linker built when it created SMP4. EXE. You can 
redirect this output to a file so you can look at it with an editor. To 
redirect it, enter: 

exehdr smp4.exe >filename 


The main message readers should get from this chapter is that all the 
previous work that has been done by the programmer, the compiler and the 
libraries comes together at the linker phase of our development cycle. The 
linker puts all this information into a form the system loader and OS/2 itself 
can understand. There are a lot of things that have to be taken care of in order 
to get our programs to run besides just reading in the program file. We will 
see more about this in the next chapter, but for now it’s important to know 
that the linker puts it all together. 


3c5 Summary 

• The linker puts everything together to make the executable. 

• The linker puts everything together by using all the information in 
the . 0B3s. Each record in the . OBJs tells the linker something. 

• The linker requires that we use either static libraries or import libraries 
to either copy the code into the executable or to point to where it is. 

® Linker options allow the programmer a bit of flexibility in structuring 
the final program. 

• The linker produces list files (. MAP) files that can be used for debug¬ 
ging. 

So now we bid a fond farewell to the lovely land of the linker. Let’s move 
on and take a look at the product of the linker, the executable module itself. 
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Every operating system has to be able to load and run programs. Each 
operating system (e.g., OS/2, DOS, UNIX) requires that these programs be 
in a specific format so that it knows how to load the program into memory, 
how to start it and whatever else may be necessary in order to run it correctly. 
It is the job of the linker to make sure that the executable programs it produces 
are in the correct format for the target operating system. As we saw in the 
last chapter, LINK386.EXE has that task for the OS/2 Operating System. 
We found that LINK386. EXE produces two types of executables: . EXE files, 
which are program files, and . DLL files which are Dynamic Link Library 
files. These executables are very similar in makeup, but different in how 
they are handled by OS/2. In this chapter, we will take a closer look at each 
type. 


41 Now That We Made It, What Is It? 

OK, now we’re ready for the good stuff. We have seen how object modules 
are put together, how library files are put together, and how the linker puts 
them all together to create our executable file. Now it’s time to put the 
executable file under the microscope. 

As we mentioned in the last chapter, the linker creates a header at the 
beginning of each executable module it produces. This header tells OS/2 
everything it needs to know about the program (or DLL) it is about to execute. 
Figure 4.1 shows the layout of the LX header used in OS/2 executable files. 
As you will notice, there are a lot of different fields, each of which means 
something different to the system. 

We will discuss a couple of the key fields, but it is beyond the scope of 
this book to discuss them all. If you are really interested in details, the 
OMF documentation mentioned throughout this book, and reproduced with 
permission in the Appendix, gives all the information for every field. 
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OFFSET 


OOh 

“L” “X”, B-ORD, W-ORD 

FORMAT LEVEL 

08h 

CPU TYPE, OS TYPE 

MODULE VERSION 

lOh 

MODULE FLAGS 

MODULE # OF PAGES 

18h 

EIP OBJECT # 

EIP 

20h 

ESP OBJECT # 

ESP 

28h 

PAGE SIZE 

PAGE OFFSET SHIFT 

30h 

FIXUP SECTION SIZE 

FIXUP SECTION CHECKSUM 

38h 

LOADER SECTION SIZE 

LOADER SECTION CHECKSUM 

40h 

OBJECT TABLE OFF 

# OBJECTS IN MODULE 

48h 

OBJECT PAGE TABLE OFF 

OBJECT ITER PAGES OFF 

50h 

RESOURCE TABLE OFFSET 

# RESOURCE TABLE ENTRIES 

58h 

RESIDENT NAME TBL OFF 

ENTRY TABLE OFFSET 

60h 

MODULE DIRECTIVES OFF 

# MODULE DIRECTIVES 

68h 

FIXUP PAGE TABLE OFF 

FIXUP RECORD TABLE OFF 

70h 

IMPORT MODULE TBL OFF 

# IMPORT MOD ENTRIES 

78h 

IMPORT PROC TBL OFF 

PER-PAGE CHECKSUM OFF 

80h 

DATA PAGES OFFSET 

# PRELOAD PAGES 

88h 

NON-RES NAME TBL OFF 

NON-RES NAME TBL LEN 

90h 

NON-RES NAME TBL CKSM 

AUTO DS OBJECT # 

98h 

DEBUG INFO OFF 

DEBUG INFO LEN 

AOh 

INSTANCE PRELOAD 

# INSTANCE DEMAND 

A8h 

HEAPSIZE 

STACKSIZE 


FIGURE 4.1 

Linear eXe (LX) Header. 
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Figure 4.1 tells us that the first two bytes of our LX header should be “L” 
“X”. This is the signature of the header; it identifies what follows as LX 
header information. 

If you were to do a dump of an executable file produced by LINK386, 
you would find that the very first byte of the file contains “M” “Z”. This 
is because the linker maintains backward compatibility to prior versions of 
operating systems, most significantly DOS. The MZ type header is/was a 
DOS compatible header. OS/2 ignores this old information and looks in 
a predetermined location, offset 0x3C (60 decimal), for the location of the 
beginning of the LX header. 

If you have a program that will do a hex dump of an executable, it is an 
interesting exercise to see if you can find the header and identify its various 
parts. Figure 4.2 is a partial listing of such a dump produced by running a 
dump program against DECODE. EXE. It shows the data in hexadecimal first, 
followed by the same data in ASCII on the following line. You will see that 
the “M” “Z” is the first byte. If you then look at offset 60 decimal (0x3C), 
you will see the value 0x80, which is the offset of the beginning of our LX 
header. At offset 128 (0x80), we see “L” “X” so we know we are looking in 
the right spot. 

Even without such a dump program, you should be able to follow along 
with the text and get the idea. There is a tool available, which we discuss 
in the next secion, that will provide you with all of the information without 
having to scan through a dump. 

In the meantime, at offset 0x3C OS/2 will find the offset (from the begin¬ 
ning of the file) where the LX header should start. At that offset it should find 
the hexadecimal code for “L” “X”, which happens to be “4C58”, marking 
the beginning of our LX header. Once the header has been located, it’s just 
a matter of searching through the data (remember, it’s in a fixed, defined 
format) for the information the system needs. 

OS/2 will look at offset 0x08 through 0x0B in the LX header to determine 
what type of processor and which operating system this module was produced 
for. In Figure 4.2 we find 0002 at location 0136. This is an 8-byte offset 
into our LX header and signifies that this module will run on an 80386 or 
upwardly compatible CPU. The 0001 in 138 says this module was meant to 
run on OS/2. 

By looking at the Module Flags field at offset 0x10, it can be determined 
whether this is an executable (. EXE) or a Dynamic Link Library (. DLL). The 
system cannot trust the name of the file; it has to look here to be certain. If 
this is a DLL, the module flags also show information about how initialization 
and termination are handled, and a couple of other things, such as whether 
this module is compatible with Presentation Manager. 

Following the module information, there are a couple of fields that point 
to where the program starts if this is an .EXE or, in the case of a DLL, where 
the initialization and termination routines start. 
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FIGURE 4.2 

Dump of DECODE.EXE Header Information. 
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All of the fields in the LX header are of interest to OS/2 but it makes 
no sense to go through them one by one here. By looking at figure 4.1 
you should get the idea. If you are able to actually poke around inside an 
executable using a dump, you should be able to work your way through the 
entire header if you desire. 

To put it in a nutshell, remember all those records types in the . OBJ files 
that we talked about in Chapter 1? The information from almost every one 
of those records gets stored somewhere in the executable module: 

@ If we have defined an import by either linking with an import library, 
or by linking with a Module Definition File for example, there will 
be a corresponding entry in the Import Module Name Table and the 
Import Procedure Name Table. 

® If this is a DLL and we made one of the functions exportable in our 
Module Definition File, there will be an entry in the Resident or 
Non-Resident Name Table. 

• If we have built a PM application and bound resources to our ex¬ 
ecutable using the Resource Compiler, there will be entries in the 
Resource Table. 

® All of the code for statically linked functions will be in the module 
and accessed via the Object Table and Object Page Table. 

• If we have compiled our program and included debugger information, 
there is a place for that also. We will talk more about this particular 
subject in Chapter 6. 

As you can see, the message here is that all the information necessary to 
load and run a program is contained in the file produced by the linker, and the 
linker adds a roadmap in the form of the LX header. When the program gets 
loaded, OS/2 looks at the header information, searches through the tables 
and pointers, and retrieves all the information it needs either from the module 
itself or, if we are importing functions, makes sure that the DLLs containing 
the imported function are available. 


42 EXEHDR.EXE - The Microscope 

There is a program that comes with the OS/2 Toolkit that most people 
never use and even many of those who do, don’t know its power. It’s called 
EXEHDR. EXE and it’s one of the best and most interesting tools you can use. 
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EXEHDR. EXE allows you to modify some portions of the executable header 
such as stack and heap size. For our purposes, though, it will list all the 
information about an executable or Dynamic Link Library that is contained 
in the header and give details about most of the table entries. The Toolkit 
documentation gives complete details about running EXEHDR. EXE. 

One of the command line options to EXEHDR. EXE is the /V (for verbose) 
option. Using this option causes EXEHDR.EXE to spew forth a wealth of 
information. It will print out: 

• DOS header information, which OS/2 doesn’t use but which is there 
for compatibility 

® OS/2 header information (our LX header information) 

• Addresses and lengths of the various tables in the executable file 

• Complete dump of the Object Table, including object attributes 

@ Runtime relocations and fixups 

® All exported entries 

For a sample of the power of EXEHDR. EXE, go to the directory where you 
built SMP1.EXE and enter: 

exehdr smpl.exe 

This will produce a standard EXEHDR output. 

Now for the real power play, enter: 

exehdr -v smpl.exe > smpl.out 


A small note about options 

When entering options, EXEHDR.EXE, as well as most other Toolkit 
utilities, will accept either a (dash) or a “/” (slash) preceding the 
letter for the option. In the case of 

exehdr -v smpl.exe >smpl.out 
the “V” can be in either upper or lower case. So -V or /v are both 
valid for EXEHDR. EXE to turn on the verbose option. 


This will give you the full load of information and redirect it to a file 
named SMP1. OUT which you can browse with any text editor. A text editor is 
necessary as there is so much information that it would scroll off the screen 
before you could get a look at it. You could also pipe it to the MORE filter, 
but that would not allow you to browse forward and backward. 
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Keeping in mind the things we have discussed so far, looking around 
the SMP1.0UT will show you how much information we can get from this 
powerful tool. It will most likely surprise you to find out that there is so much 
contained in our simple little program. Remember that when we write in C, 
we are writing at a very high level, and the C functions call OS/2 functions, 
so a lot of what you see here happens without any help from the programmer. 
It’s all put there by the compiler and the linker. 


43 Dynamic Link Libraries 

As you should know by now, DLLs are very similar to executable program 
files. That is, they are created by the linker, have a LX header and are loaded 
into the operating system in the same way as a program file is. There are 
some minor differences, however. For example, the LX header has some 
information that is peculiar to DLLs, such as Initilization/Termination code. 
But the general makeup of a DLL is like an . EXE file. 

The module definition file we use to create the DLL is what makes most of 
the difference. Figure 4.3 is a listing of the Module Definition File used to 
build the DLL in SMP5. 

The LIBRARY statement tells the linker that this will be a DLL and supplies 
a name for that DLL (SMP5DLL) 

The PROTMODE statement indicates that this DLL is a protected (OS/2) mode 
only DLL. 

The DATA statement defines the attributes for the data segments within the 
DLL. In this case, MULTIPLE specifies that each process using the DLL will get 
its own copy of the data segment. READWRITE indicates the data segment can 
be read from or written to. LOADONCALL tells OS/2 to load the data segment 
into memory the first time it is accessed. 

CODE LOADONCALL defines the attributes of the code segment. It means 
that the CODE segment will be loaded when called. 


A word about PRELOAD and LOADONCALL 
OS/2 is a demand paging system. What actually happens if we define 
PRELOAD for example, is that OS/2 sets up the tables etc. as IF we 
loaded the segments, but they do not actually get loaded into physical 
memory until an attempt is made to access one. Then there is a page 
fault generated. It’s the page fault that actually causes the segment 
to be read into memory. 


Last but not least, the EXPORTS statement tells the linker which functions 




58 


4. THE EXECUTABLE MODULE 


; SMP5DLL.DEF - DLL Sample program dynamic linking library definition file 


LIBRARY SMP5DLL 

DESCRIPTION ’OS/2 32-bit DLL - Standalone without C Run-Time Libraries’ 
PROTMODE 


DATA MULTIPLE READWRITE LOADONCALL 

CODE LOADONCALL 

EXPORTS 

WordCnt 
_PGLOBAL_PTR 
_critlib_except 
_DosSelToFlat 
_DosFlatToSel 
stderr 
stdi n 
stdout 
_CRT_init 
fopen 
fclose 
_environ 
_EXE_Exception 
_Exception 
_PrintErrMsg 
_exception_procinit 
_exception_dl1init 
_matherr 
_printfieee 
_terminate 
exi t 
free 
malloc 
printf 
scanf 
strdup 
strpbrk 
fgetc 


* * * * 
it it it it 
it it it it 


it it it it 
it it it it 
it it it it 
it it it it 
it it it it 


it it it it 


it it it it 

JU JU *»- 


FIGURE 4.3 

Sample Definition File for DLL. 
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to export from this DLL and make available to other executables. You will 
see a bunch of exports from this DLL. Our sample shows one of the major 
benefits of DLLs: to reduce the size of our executables. What we did was 
to statically link SMP5DLL.DLL, which will include the C runtimes in the 
DLL, then export the functions we need using the module definition file, 
SMP5DLL. DEF shown in Figure 4.3. 

When SMP5.EXE was built, we didn’t link with the standard libraries, 
but rather used SMP5LIB.LIB, the import library for SMP5DLL.DLL. This 
was accomplished in the makefile by using the /NODEFAULTLIBRARYSEARCH 
(/NOD is the short form) option when calling LINK386 during the creation 
of the . EXE. The /NOD tells the linker to not use the default libraries and to 
use only those entered as arguments to the “Li brari es:” prompt. Because 
SMP5DLL.DLL is exporting all the functions we need, our executable only 
gets the ones it needs, thus our executable is much smaller. You can see 
for yourself the significant difference in file size between SMP4.EXE and 
SMP5. EXE by doing a DIR command on each of them. 

The exports with ;**** following them are always required when you 
include C runtimes in your DLLs. They are used by startup functions in the 
calling executable or DLL. The compiler User’s Guide gives more details. 
The other functions, those without ;****, are required by SMP5. EXE. 

What you should see from SMP5 is that by putting our runtimes in the DLL 
and exporting them, any programs calling the DLL are significantly smaller. 
When we have a lot of programs accessing a DLL in this manner, there can 
be a real savings in disk space. 

This is a fairly simple Module Definition File. There are many other 
options and variations. The online reference for LINK386. EXE has an entire 
section on Module Definition Files. Please refer to it for further details. 

Now let’s get back to EXEHDR. EXE. EXEHDR. EXE can be used to get infor¬ 
mation about a DLL as well as an . EXE file. If you go to the directory where 
you built SMP3 and enter: 


exehdr -v smp3dll.dll > smp3dll.out 


you will get all the info about SMP3DLL.DLL in the file SMP3DLL.0UT. 
Browse through the file and see if you can figure out what is there. The 
output will be very similar to that of an .EXE file. One of the things to look 
for in the EXEHDR.EXE output from a DLL is the list of exports. 

The imports in an . EXE or . DLL are listed in another section. We’ll take 
a closer look at EXEHDR.EXE in the next chapter, but first let’s talk a little 
about ordinals and FWDSTAMP. EXE. 
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44 Ordinals 

We have to include a few words about ordinals. As you explore some of 
these files and listings, you will notice that functions in DLLs are sometimes 
referred to by name, such as SMP5DLL.WORDCNT indicating the WordCnt 
function within SMP5DLL.DLL. Other times, you may see something like 
SMP5DLL.123orSMP5DLL @12 3 . In these cases, the “ 123” is what is referred 
to as the ordinal of the function. What the ordinal really amounts to is 
an index (or offset) into a table or list within the DLL used to locate the 
function. Ordinals can be assigned by the programmer or by the linker. When 
we are building our DLLs, we can assign ordinal numbers via the Module 
Definition File. Internal searches within the DLL are done by ordinal number, 
so sometimes performance can be improved by assigning low ordinals to 
functions you expect to be used frequently. 

Those of you using the OS/2 Warp Toolkit can take a look in T00LKIT\H 
at a file, BSEORD. H, which defines the ordinals for OS/2 functions. There 
are some OS/2 functions, such as DosQueryProcAddr, that can be used with 
either a procedure name or an ordinal. DosQueryProcAddr is used to obtain 
the address of a specific procedure (function) within a DLL by passing either 
a procedure name string or an ordinal as one of the parameters. It will return 
the address of the procedure. 

Some of the Do sxxx procedures are ONLY accessible using the ordinal. 
This is because of the way some of these references are resolved and where 
the actual code for the procedure resides. We’ll talk more about how OS/2 
resolves these references in a later chapter. If you were writing a program 
requiring you to get the address of, say, DosMakePipe, you would look in 
BSEORD . H for the #define 0RD_D0SMAKE PI PE statement. There you would 
find the ordinal is 16, which you would pass to DosQueryProcAddr as the 
ulordinal parameter. 

In actual practice you would just pass the constant ORD_DOSMAKEPIPE. 


45 DLL Tricks With FWDSTAMP.EXE 

This is probably a good time to talk about the FWDSTAMP. EXE utility. FWD¬ 
STAMP.EXE is a utility that is part of the OS/2 Toolkit which is provided 
on the Developer Connection for OS/2. 

Let’s suppose that you wrote an application that included two DLLs called 
ONE. DLL and TWO .DLL. Each of these DLLs exports some if its functions. 
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Some time down the line, for whatever reason, you decide that you want 
to replace ONE. DLL and TWO. DLL with a single DLL we’ll call NEW. DLL. 

If you were to provide NEW. DLL only to the users of your application, it 
wouldn’t work the way you wanted it to, because the application is importing 
functions from the original DLLs and knows nothing about NEW. DLL. 

What FWDSTAMP. EXE allows you to do is create special kinds of references 
in DLLs, called forwarders. Forwarders are new entry points for functions 
that are to be replaced. They point to the replacement code which is in 
another DLL. In our case, we would run FWDSTAMP against ONE.DLL and 
TWO.DLL and tell them to “forward” references to functions within them to 
the new functions in NEW.DLL. 

What actually happens is that FWDSTAMP. EXE creates copies of the original 
DLLs that are identical to the originals with the exception that some or all 
of the entry points are pointing (forwarded) to our NEW. DLL. The forwarders 
are imported exports, if you will. We import them from another DLL and 
export them to the executables as if they were in the DLL the executable 
thinks it is using. 

The beauty of FWDSTAMP. EXE is that it allows you to do this without having 
to change or rebuild the application. If you have users who are also writing 
code that imports from your DLLs, they also can be spared the pain. All you 
would have to do is provide the updated DLLs (those with the forwarders) 
and the new DLL. 

There is virtually no limit to the number of forwarders you can use. (Ac¬ 
tually, there is a limit of 1024, but we doubt that anybody will ever reach 
it.) The loader will get an error if you exceed that number or if you create a 
circular reference, one that forwards back to itself. 

The loader follows the forwarders to an export reference that has no for¬ 
warder attached. This becomes the function used. All this magic occurs as 
the result of entries in a Module Definition File. 

SMP6 is a simple example of how to use FWDSTAMP.EXE. We first built 
SMP6DLL. DLL and put two functions in it, WordCnt and CharCnt. As their 
names imply, one counts the number of words in a text file, the other counts 
characters. 

The makefile also creates NEW.DLL and puts Mywc in it. Mywc is an im¬ 
proved version of both of the functions in SMP6DLL. DLL. The idea here is 
to run FWDSTAMP.EXE against SMP6DLL.DLL, put forwarders on WordCnt 
and CharCnt, and have them both replaced with the new, improved Mywc in 
NEW.DLL. 

There is also REPL. CMD in the SMP6 directory. This is an OS/2 command 
file that actually runs FWDSTAMP. EXE and replaces the original SMP6DLL. DLL 
with the new one containing the forwarders. FWDSTAMP. EXE creates MY. DLL, 
which will eventually become the replacement SMP6DLL. DLL. 

If you run SMP6. EXE and pass it the names of up to ten text files, you will 
see the WordCnt and CharCnt functions being called and their printouts. 



62 


4. THE EXECUTABLE MODULE 


Once you see how it operates, ran REPL. CMD. It will output to the screen the 
individual steps it is taking. After it ends, ran SMP6. EXE again and notice 
the difference. You will see that the new Mywc function, in NEW. DLL, is being 
executed twice for each file. This is because both WordCnt and CharCnt 
have been forwarded to Mywc. 

To get back to the original versions, run BACK. CMD, another OS/2 command 
file provided in the SMP6 directory. 


4.6 Is It Realty Happening? 

If you’d like to try an experiment, rename NEW.DLL to something such 
as NEW.XXX before running REPL.CMD. Running SMP6.EXE is no problem. 
After you run REPL. CMD, though, you will get a message that SMP6 can’t 
find the file NEW. This proves that NEW.DLL is actually being called via the 
forwarders in the replacement SMP6DLL. DLL. 

Figure 4.4 shows the two files that accomplish the forwarding, MY.DEF 
and REPL. CMD. 

Figure 4.5 illustrates SMP6.EXE and SMP6DLL.DLL before 
FWDSTAMP.EXE is run. 

Figure 4.6 shows the relationship after FWDSTAMP.EXE is run. Note the 
way the wordcnt and charcnt functions have BOTH been replaced by mywc. 

As you will notice, MY. DEF looks as if it is creating the library SMP6DLL. 
Actually it is creating the replacement for it. This file is input to 
FWDSTAMP.EXE, which we’ll take a look at in a minute. Also notice that we 
are importing NEW. MYWC (the Mywc function in NEW. DLL) as both WORDCNT and 
CHARCNT and that we are exporting WORDCNT and CHARCNT. It is this combina¬ 
tion of IMPORT and EXPORT of the same function that causes FWDSTAMP. EXE 
to create the forwarders in MY. DLL. 

Taking a look at REPL. CMD and in particular the call to FWDSTAMP. EXE: 
fwdstamp -v smp6dll.dll my.def my.dll 

As mentioned above, the -V is the verbose option, causing maximum 
information output from FWDSTAMP. EXE. 

We are operating on SMP6DLL .DLL, creating MY. DLL and controlling things 
with MY.DEF. 

FWDSTAMP. EXE provides us with a very powerful, useful tool. Hopefully, 
the previous discussion will help you to understand how it can be used. 
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; MY.DEF - DLL Forward Stamp definition file 
LIBRARY SMP6DLL 

DESCRIPTION ’OS/2 32-bit DEF - Used in forwarding’ 
IMPORTS 

WORDCNT - NEW.MYWC 
CHARCNT = NEW.MYWC 

EXPORTS 

WORDCNT 

CHARCNT 


REPL.CMD 


echo off 

echo Running Sample with input from SMP6.C 
echo. 

smp6 smp6.c 
echo. 
echo. 

echo Running FWDSTAMP to create replacement, MY.DLL 

echo. 

echo. 

fwdstamp -v smp6dll.dll my.def my.dll 

echo. 

echo. 

echo Renaming original SMP6DLL.DLL to SMP6DLL.ORG 
echo. 
echo. 

rename smp6dll.dll smp6dll.org 

echo. 

echo. 

echo Copying replacement, MY.DLL to SMP6DLL.DLL 
echo. 
echo. 

copy my.dll smp6dll.dll 

echo. 

echo. 

echo Now to re-run same program with replaced DLL. 


echo. 

smp6 smp6.c 


FIGURE 4.4 

SMP6—-Example of FWDSTAMP. 
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SMP6DLL.DLL SMP6.EXE 



FIGURE 4.5 

SMP6 before running FWDSTAMP.EXE 


SMP6DLL.DLL SMP6.EXE 



FIGURE 4.6 

SMP6 after running FWDSTAMP.EXE 
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4.7 Summary 

® The linker puts the LX header at the beginning of all . EXEs and .DLLs. 
The header contains the information necessary to run the file. 

« EXEHDR. EXE is a tool that can be used to examine most of the impor¬ 
tant information about executable files. 

• Ordinals can be used in place of procedure names in DLLs, and in 
some cases must be used. 

® FWDSTAMP.EXE can be used to combine DLLs or to replace indi¬ 
vidual procedures within DLLs without having to rebuild and relink 
applications. 

In the next chapter, we will take a closer look at EXEHDR. EXE and what it 
can tell you. We’ll also get a better feel for the actual structure of the . EXE 
and .DLL. 




5 

A Closer Look at EXEHDR 


As mentioned in the last chapter, EXEHDR. EXE is one of the most powerful 
tools available for poking around and obtaining information about your ex¬ 
ecutable files. Many people don’t know its full capabilities. EXEHDR. EXE 
will allow you to modify some items in the LX header, such as the stack size 
or the heap size to help you tune the way your program runs. These options 
are fully discussed in the online reference. 

What we would like to discuss here is the wealth of information available to 
you in the verbose output listing of EXEHDR. EXE. When you run EXEHDR. EXE 
against an .EXE or a .DLL and specify the /v option, you will get a pile of 
useful information - basically all the things in the LX header that the OS/2 
loader and OS/2 itself need to run a program. 

The verbose output from EXEHDR. EXE is considered invaluable informa¬ 
tion for debugging applications and DLLs, and after we take a closer look, 
you will probably agree. 


5.1 Inside Our DLL 

We’ll start by taking a look at what NEW. DLL has to tell us. Go to the SMP6 
directory and at the command line enter: 

exehdr /v new.dll > new.out 

NOTE: As mentioned in prior chapters, options can be entered with either 
a slash, 7’ or a dash, ‘-’ and may be in either upper or lower case. 

You may as well also get the output from SMP6DLL. DLL and SMP6. EXE, 
as you’ll probably want to look at them next. Use the copy of SMP6DLL. DLL 
with the forwarders in it (after you run REPL. CMD). Enter: 

exehdr /v smp6dll.dll > smp6dll.out 


then 
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exehdr /v smp6.dll > smp6.out 

Now we have all that EXEHDR. EXE has to tell captured in three files. Look 
at NEW.OUT with your favorite text editor. We chose NEW.OUT because it 
has a few more points of interest than either SM6DLL. OUT or SMP6. OUT. You 
can look at the SMP6DLL. OUT and SMP6. OUT later and you should be able to 
interpret the information contained in them. If you prefer to run EXEHDR. EXE 
against some other . EXE or . DLL, you should still be able to follow along. 
Figure 5.1 is a copy of the first part of the listing from NEW. DLL. 

The first part, up to and including “Memory needed”, is the DOS compat¬ 
ible portion we talked about earlier. The only part of this that OS/2 cares 
about is the entry for the location of the “New executable header address:”. 
In this case, it is 0x80, which means that the LX portion of the header starts 
at offset 0x80 or 128 decimal. If you have a program that can do a hexadec¬ 
imal dump of NEW. DLL, or you want to load it into a debugger, it is possible 
to follow along with the text and locate the things we talk about. It’s not an 
exercise we would recommend for everybody, but we know there are some 
curious folks out there. 

When OS/2 loads this DLL, it will locate the beginning of the LX portion 
of the header and start looking at that offset for the information it will need 
to execute this code properly. The remainder of Figure 5.1 is derived from 
the LX portion of the header. 

A couple points of interest are: 

The module type tells us that this is a DLL, not an executable program, 
and that it is using Global Initialization and Termination. The linker docu¬ 
mentation will tell you that INITGLOBAL and TERMGLOBAL are the defaults. 
Since we didn’t specify in NEW.DEF when we built NEW.DLL, defaults are 
used. 

The number of memory pages tell the loader how much physical memory 
is needed to run this program. Looking back at Figure 4.1 (page 52), we see 
that this information is stored at offset 0x14 in the LX portion of the header. 
If you are looking at the binary content of the file with a debugger or dump 
program, you should see a “04” at offset 0x94 (148 decimal). 

Because this is a DLL and not a program, the CS:EIP value tells the 
location of the Initialization/Termination routine. If this were a program, 
this value would represent the starting point of the program and the value of 
SS: ESP would locate our stack, but since it is a DLL and a DLL uses the 
caller’s stack, SS: ESP is all zeroes. 

There is an entry labeled “Resident Names Table:” located at offset 0x194 
(404 decimal) and has a length of 0x14 (20 decimal). DLLs maintain two 
tables, a Resident Names Table and a Non-Resident Names Table. These 
tables contain entries that define the ASCII name strings and ordinal numbers 
of procedures within this module. The tables are used to translate procedure 
names to ordinal numbers. (You may want to refresh your memory a little 
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.EXE size (bytes) 

3c00 


Magic number: 

5a4d 


Bytes on last page: 

0200 


Pages in file: 

0005 


Relocations: 

0000 


Paragraphs in header: 

0004 


Extra paragraphs needed: 

0000 


Extra paragraphs wanted: 

ffff 


Initial stack location: 

0008: 

: 0200 

Word checksum: 

0000 


Entry point: 

0000: 

o 

o 

o 

o 

Relocation table address: 

0040 


Reserved words: 

0000 0000 0000 0000 0000 

0000 

0000 0000 

0000 0000 0000 0000 0000 

New executable header address: 

00000080 

Memory needed: 

3K 


Library: 


NEW 

Executable format level: 


0 

CPU type: 


Intel 80386 or upwardly 

Operating system: 


compatible 

Operating System/2 

Module version: 


20000 

Module type: 


Dynamic link library 

Number of memory pages: 


Global initialization 
Global termination 
00000004 (4) 

Initial CS:EIP: 


object 1 offset 00000708 

Initial SS:ESP: 


object 0 offset 00000000 

Automatic data object: 


2 

Memory page size: 


00001000 

Page shift alignment: 


00000009 

Fixup section size: 


00000660 

Fixup section checksum: 


00000000 

Loader section size: 


00000068 

Loader section checksum: 


00000000 


FIGURE 5.1 

EXEHDR Output of NEW.DLL. 
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Object Table: 00000144 length 00000050 (80) 

Object Table Entries: 00000002 (2) 

Resource Table: 00000000 length 00000000 (0) 

Resource Table Entries: 00000000 (0) 

Resident Names Table: 00000194 length OOOOOOOe (14) 

Entry Table: 000001a2 length 0000000a (10) 

Module Directives Table: 00000000 length 00000000 (0) 

Module Directives Entries: 00000000 (0) 

Per-Page Checksum Table: 00000000 length 00000000 (0) 

Imported Modules Name Table: 000007b6 length 00000019 (25) 

Imported Modules: 00000004 (4) 

Imported Procedures Name Table: 000007cf length 0000003d (61) 

Preload Instance Pages: OOOOOaOO number 00000000 (0) 

Preload Pages: OOOOOaOO number 00000000 (0) 

Demand Instance Pages: OOOOOaOO number 00000000 (0) 

Non-resident Names Table: 00000000 length 00000000 (0) 

Non-resident Names Checksum: 00000000 

Debug Information: 00000000 length 00000000 (0) 

Library: NEW (DLL Name) 


Module type: Dynamic Link Library (This is a DLL) 
Global initialization 


Number of memory pages: 00000004 

Initial CS:EIP: object 1 offset 00000708 (Init/Term 

addr/Prog Start) 

Initial SS:ESP: object 0 offset 00000000 (Stack Pointer) 
Resident Names Table: 00000194 length OOOOOOOe (14) 


Imported Modules: 00000004 (4) (Importing from 4 other DLLs) 


FIGURE 5.1 (continued) 
EXEHDR Output of NEW.DLL. 
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about ordinals. We discussed them in Chapter 4.) The ordinal number is the 
reference used to locate the procedure entry point in another table called the 
Entry Table. The Resident Names Table is kept in system memory whenever 
the DLL is loaded, and the Non-Resident Names Table is only loaded when 
needed. The idea is to have frequently used entries in the Resident Table and 
rarely used entries in the Non-Resident Table. This is a trade-off between 
performance and memory utilization. The fastest way to find any procedure 
is to call it by ordinal and eliminate the name-to-ordinal search. 

The linker online documentation tells us that the way we define the EXPORTS 
in the Module Definition File determines which names table our EXPORT will 
be contained in. If we use the RESIDENTNAME modifier with the EXPORT key¬ 
word for our functions, they will show up in the Resident Names Table. 
Those exports declared by name only are also part of the Resident Names 
Table. Those declared only by ordinal go into the Non-Resident Names 
Table. 

The Imported Modules line tells us we are importing from four other DLLs. 
This is not the number of imports in the executable. Later, when we look at 
the fixups and count the imports, we will find many imports mentioned, but 
they are all coming from only four DLLs. 

The rest of figure 5.1 contains more information necessary to load and 
execute this DLL or program. If you are interested in diving further into this, 
it is documented in great detail in the IBM OS/2 16/32-bit Object Module 
Format (OMF) and Linear executable Module Format (LX) document (see 
the Appendix). 


5.2 The Object Table 

Figure 5.2 shows the next part of the EXEHDR.EXE output from NEW. DLL. 
If you’re following along in a dump or debugger, the header information (see 
Figure 5.1) tells us that the Object Table is stored starting at location 0x144 
or 324 decimal. The Object Table gives information about the two memory 
objects contained in the DLL code. 

Referring to Figure 5.2, we see that the first object, which happens to be 
the code portion, is 0x2a34 (10804 decimal) bytes long. It contains three 
pages (labeled “map size” because the page map has three entries), and the 
first page in the object is page number 1 (map index 1). The flags for this 
object tell us it is EXECUTABLE, READABLE, etc., which is what we should 
expect for the code portion of an executable. 

Also notice that the three pages (page map entries) are listed giving their 
size, addresses and flags. 
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The second object is 0x670 (1648 decimal) bytes long and contains only 
one page. Note that this page plus the three pages in the first object total four, 
which matches the “Number of memory pages:” field in the LX header. 

The first (and only) page in this object is page 4 of our executable (page 
map index). It too is a 32-bit object, but this time it is our data and is not 
executable. 


16/32 Bit Operation 

A note here about 16/32 operation. There is a 32-bit flag in each of 
these objects that denotes them as 32-bit objects. This flag is the only 
way OS/2 can distinguish between 16-bit and 32-bit operations. We 
talked previously about the SEGDEF records. The Segment Attribute 
field of the SEGDEF record type contains a bit field (the P bit field, to 
be specific). The setting of the P bit determines the addressing used 
for that particular segment. This is the only way to define whether 
the segment is a 16-bit segment or a 32-bit segment. It in turn results 
in the setting of the 32-bit flag in the object table. 


5.3 Exports 

At the end of Figure 5.2 is a list of exports. In this case there is only one 
entry, MYWC, and its ordinal was assigned by the linker as 1. If you look at 
the SMP6DLL .OUT, you will see a much longer list. 


5.4 Relocation and Fixups 

When OS/2 loads a program for execution, it can be loaded any place 
in available memory. When one part of a program is referenced by some 
other part of the program, the relationship between the address that does 
the referencing (referred to as the source) and the address or object that is 
referenced (known as the target) must be maintained in order for the program 
to run correctly. This is done by what are known as fixups. Fixups are records 
in the executable module that are “instructions” to the OS/2 loader. They 
tell the loader what addresses have to be “fixed up” to ensure the original 
relationship is maintained. There are two tables in the header of the program 
that contain the fixup information. The Fixup Page Table maps to a Fixup 
Record Table for each page of the executable, (see the Appendix for details) 
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no. virtual virtual map map flags 

address size index size 
0001 0010000 00002a34 00000001 00000003 EXECUTABLE, 

READABLE,NONSHARED, 

L0AD0NCALL, NONCONFORMING, 
NONRESOURCE, NONDISCARDABLE, 
VALID-PAGES, SWAPPABLE, 

NO 16:16 ALIAS, 32-bit, N0I0PL 
map physical page flags 
entry page @ size 
00000001 OOOOOaOO 1000 VALID 
00000002 OOOOlaOO 1000 VALID 
00000003 00002a00 OcOO VALID 
0002 0002000 00000670 00000004 00000001 READABLE, 

WRITEABLE, SHARED, LOADONCALL, 
NONRESOURCE, NONDISCARDABLE, 
VALID-PAGES, SWAPPABLE, 

NO 16:16 ALIAS, 32-bit, NOIOPL 
map physical page flags 
entry page @ size 
00000001 00003600 0600 VALID 


Exports: 

ord obj offset name 

1 1 00000000 MYWC exported, shared data 


FIGURE 5.2 
Object Table. 


If you go back and take another brief look at Chapter 1, you will see men¬ 
tion of FIXUPP records that are put into the .OBJ files. The FIXUPP records 
describe what address relationships have to be fixed up in that particular 
.OBJ file. The linker takes all the .OBJs and gathers up the data from all the 
FIXUPP records to create the final fixups (in the Fixup Record Tables) when 
the executable file is generated. 

Each fixup in the executable has a set of similar fields: a source offset, a 
source type, a target flag and target data. 

The source offset tells the loader where in the page the fixup is to be applied, 
while the source type defines what type of fixup to apply. The source could 
be, for example, a 32-bit pointer, a 16-bit selector or any of a number of other 
types. In order to generate the proper source/target relationship, the loader 
must know what type the source is. 

The target flag tells the loader what this source is referring to, and the 
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target data gives specifics depending on what that target is. For example, if 
the source is referring to a procedure in a DLL, the target flag will identify 
the target as an import and the target data will specify which routine in which 
DLL is to be imported. 

There are any number of different combinations of source types, target 
flags and target data. They are all similar in that they specify what we have 
to supply to the source offset to resolve the original reference. 

Figure 5.3 shows part of the fixup section output produced by EXEHDR. EXE 
running against NEW. DLL. We would suggest you redirect the output to a file 
(we used NEW.OUT) to preserve the information, then look at it with your 
favorite editor. 

Look at the first entry in Figure 5.3. This happens to be a chain (string of 
offsets) of eight fixups. There are eight offsets in page 1 of object 1 beginning 
at address 0x167 and going to 0x9ca. 

The target tells us we are going to resolve these references by importing 
DOSCALLS .2 56, which happens to be the 32-bit version of DosSetFi 1 ePtr 
(according to BSEORD. H). This record then tells us that we will apply fixups 
at eight places to import DOSCALLS .256. 

Two lines later we see one of our SMP6DLL functions (_PRINTFIEEE) being 
imported. 

Note that we have several imports from DOSCALLS. DLL and two from 
SMP6DLL. DLL shown in Figure 5.3. If you scan the entire NEW, OUT file, you 
will find that we have many imports, but we only import from four different 
DLLs: DOSCALLS, SMP6DLL, MSG and NLS. This will match the number in the 
Imported Modules field of the LX header. For those of you looking at a dump, 
the header tells us that the Imported Modules Name Table is at offset 0x7b6 
(1974 decimal). If you look there, you should see the hex representation of 
our four module names. 

Further down Figure 5.3, we see a 32-bit fixup from offset 111 in object 
1 to offset 0000 in object 2. This is a reference to something in the data 
section (object 2) of our program. We have marked it with an arrow to make 
it easier for you to spot. There is not enough detail in the printout to identify 
exactly what the item is, but if the linker and loader do their job correctly, 
we don’t have to worry about it. 

This part of the listing gives a lot of information, but its most useful 
feature is to see what is being imported. The imports aren’t listed anyplace 
else unless you have the . MAP file from the link operation. 

This pattern of fixups continues until all the fixups necessary to make the 
addresses come out correctly are applied. Remember, what we are looking at 
here are records inserted in the DLL (or . EXE) by the linker. They represent 
what has to be done by the OS/2 loader when it loads this file and OS/2 
prepares to execute it. 

If you compare the output generated by EXEHDR. EXE from SMP6. EXE and 
NEW.DLL you will see similar listings. Notable differences in SMP6. EXE: 
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page 1 type offset target 

obj 1:0000 REL OFF(32) chain:08 imp DOSCALLS.256 

0167 Olal 02dc 03d2 0476 063f 0686 09ca 
REL 0FF(32) 0b49 imp NLS.6 

REL 0FF(32) chain:02 imp SMP6DLI_PRINTFIEEE 

0116 012f 

REL 0FFC32) 008c imp SMP6DLL.FGETC 

REL 0FF(32) chain:02 imp DOSCALLS.282 

0379 0421 

REL OFF(32) 0d45 imp DOSCALLS.348 

REL 0FF(32) 0a77 imp DOSCALLS.224 

REL OFF(32) chain:07 imp DOSCALLS.299 

0330 0be9 0c26 Oc57 0c94 0cc5 0d02 
REL 0FF(32) chain:04 imp DOSCALLS.304 
0495 0fl3 0f2b 0f43 

REL OFF(32) Oade imp DOSCALLS.312 

REL OFF(32) 0fd3 imp DOSCALLS.378 

-»»»» OFFSET(32) 0111 object 2 offset 0000 

OFFSET(32) chain:14 object 2 offset 0600 

017c 01b6 023b 0285 02fl 0341 0399 043d 04da 0513 
052f 0547 057c 064f 0696 06b9 08ab 08bd 08ec 09dd 
OFFSET(32) Od65 object 2 offset 0240 

OFFSETC32) 0c21 object 2 offset 0144 

OFFSET(32) Ocfd object 2 offset 0204 

OFFSET(32) chain:06 object 2 offset 05c8 

07b6 07fe 080e 081e 0851 0ff6 
OFFSET(32) chain:03 object 2 offset 0108 

0ba9 0be4 OcOf 

OFFSET(32) chain:04 object 2 offset 01c8 

Obbd 0bd8 OccO Oceb 

OFFSET(32) 0d2b object 2 offset 0648 

OFFSET(32) chain:02 object 2 offset 024c 

0ab9 0ba3 ' 

OFFSET(32) Od35 object 2 offset 064c 

FIGURE 5.3 
Fixups in NEW.DLL. 


Module type: Program 

Initial CS:EIP: object 1 offset 0000010c 

Initial SS:ESP: object 2 offset 000080a0 


The Stack Pointer (SS: ESP) is no longer 0 (as shown in Figure 5.2) because 
SMP6. EXE is a program and not a DLL. CS: EIP and SS: ESP now represent 
the entry point and the location of the program’s stack, respectively. 

Figure 5.4 shows another interesting piece of information. It is the list 
of exports from the SMP6DLL.DLL we created in sample SMP6. This is the 
one after FWDSTAMP was run. Take a look at ordinals 21 and 24. Note 
that they both say “forwarded to NEW.MYWC”. These forwarders were put 
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there by FWDSTAMP.EXE. When any program calls CHARCNT or WORDCNT 
in SMP6DLL.DLL, these forwarders will cause the code in function MYWC 
in NEW.DLL to be executed in their place. Also notice that both functions 
are being replaced by a single function in NEW. DLL while all the others in 
SMP6DLL. DLL remain unchanged. 


Exports: 


ord obj offset 

name 


1 

1 

00001958 

_EXCEPTI0N_PR0CINIT exported, shared data 

2 

1 

00004054 

_PRINTFIEEE exported, shared data 

3 

2 

0000007c 

_PGLOBAL_PTR exported, shared data 

4 

1 

00001d50 

_PRINTERRMSG exported, shared data 

5 

1 

00008a7c 

_D0SSELT0FLAT exported, shared data 

6 

1 

00008a84 

_D0SFLATT0SEL exported, shared data 

7 

1 

00000c08 

FREE exported, shared data 

8 

1 

00001178 

EXIT exported, shared data 

9 

1 

00001210 

_EXE_EXCEPTION exported, shared data 

10 

1 

000060c4 

SCANF exported, shared data 

11 

1 

00006e30 

FGETC exported, shared data 

12 

2 

00000070 

STDIN exported, shared data 

13 

1 

00006248 

F0PEN exported, shared data 

14 

1 

00000930 

MALL0C exported, shared data 

15 

1 

00006d20 

FCL0SE exported, shared data 

16 

1 

00004338 

PRINTF exported, shared data 

17 

2 

00000078 

STDERR exported, shared data 

18 

2 

00000074 

STD0UT exported, shared data 

19 

1 

00001fe4 

STRDUP exported, shared data 

20 

1 

00001a04 

_CRITLIB_EXCEPT exported, shared data 

21 

0 

00000000 

CHARCNT forwarded to NEW.MYWC 

22 

1 

000090e4 

JMATHERR exported, shared data 

23 

1 

0000204c 

STRPBRK exported, shared data 

24 

0 

00000000 

WORDCNT forwarded to NEW.MYWC 

25 

2 

000012fO 

_ENVIR0N exported, shared data 

26 

1 

00001928 

_EXCEPTION_DLLINIT exported, shared data 

27 

1 

00000268 

_CRT_INIT exported, shared data 

28 

1 

OOOOllfO 

_TERMINATE exported, shared data 

29 

1 

OOOOlbec 

.EXCEPTION exported, shared data 

FIGURE 5.4 




Exports from SMP6DLL.DLL 



You get the idea. There is a lot of information available and, granted, 
not all of it is important all the time. What we have tried to show is an 
overview of what is available, how to look at it and a brief idea of how it all 
fits together. We only scratched the surface but if you are interested in going 
further, you have a good foundation to start from. If you experiment on your 
own looking at different files, you will soon begin to see what the important 
and interesting things are. 
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5o5 Who Cares About All This Detail? 

You may ask “Who cares about all this detail?” and that’s a fair question. 
Some people really couldn’t care less about this information and survive for 
years without ever having (or wanting) to know anything about what the 
inside of a program file looks like. But there are some curious people who 
just like to know how things tick. At the same time, there are others who 
either have to learn or wish they knew some of the details. 

Digging in to this level of detail makes a lot of things about how the 
operating system itself actually operates easier to understand and explain 
while providing a little more ammunition for problem solving. 


5o6 Summary 

• EXEHDR.EXE can be a valuable tool for inspecting programs and 
DLLs. 

• Additional documentation is available (as mentioned throughout this 
book) for the curious. 

In the prior chapters we have explored how program files and their com¬ 
ponent parts are put together. In the next chapter, we will learn about some 
related topics such as debugging and debuggers, OS/2s system DLLs and a 
couple of other subjects you should find interesting. 
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There’s more to just writing your source code, compiling it and watching it 
run. In this chapter, we’ll take a look at other aspects of the process, not 
covered in previous chapters. We’ll learn what happens to your files if you 
have to debug your program. You’ll see how calls to OS/2 system DLLs get 
resolved. Then we’ll discuss 16-bit vs. 32-bit operation plus a couple other 
goodies. 


6.1 Debugging 

First, let’s talk a little bit about debugging. Most of us never have to 
debug anything because we write such perfect code. But even the most 
proficient programmers have gained expertise in debugging because they 
found themselves in the position where something they wrote didn’t work 
exactly the way it was supposed to. Fortunately, the compiler writers and 
system designers allowed for this possibility and put some things in place to 
help. 

Compilers always have an option to include or exclude debugging infor¬ 
mation. If we choose not to include the information, we end up with smaller, 
faster running executables. However, if we compile with the debugging in¬ 
formation included, the compiler obliges by adding more information to the 
„OBJs created, things like additional symbol information, line numbers and 
so on. These are the things debuggers such as the one that comes with IBM 
C Set-H-, IPMD. EXE, use to assist us in fixing our code. 

If you were to build any of our samples with debugging information in¬ 
cluded and compared the . OBJs generated to those created without debug 
information, you would find that the ones with the debug information are al¬ 
ways larger. Furthermore if you were to run DECODE. EXE against the modules 
and look at the differences, you would see that there were some additional 
records generated for the debug version. 
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Most compilers also provide some sort of debugger as part of the package. 
Not all debuggers use the same format for the debug information. The 
compiler and debugger pair understand the format used. There are some 
formats that are understood by OS/2 and DOS, while others work with UNIX. 

When debug information is included, the compiler will add an additional 
COMENT class A1 record to the object indicating which type it generated. 
Other records (such as LINNUM 94H or 95H) will be added and modified as 
necessary to include the correct information for the target type of debugger. 


Try this Experiment 

An experiment for you to try is to take one of the samples and compile 
it with and without debug information, run DECODE. EXE against each 
and compare the differences. See if you can explain what you see. 


6.2 What the Linker Does to Help 

The linker gives the debug information a place to stay in the executable. 
There are two fields in the LX header (at offset 98H) that point to the off¬ 
set of the debug information and give its length. LINK386. EXE will create 
these entries in the header and put a type code at the beginning of the debug 
information denoting the format of the information. Other than that, the in¬ 
formation is just copied into the executable. It is left to the compiler/debugger 
programs to encode and decode the information. 

If you compile one of the sample source files with the debug option set to 
include the debug information (/Ti + in C Set++) and the compile only flag 
(/C), you will get a . OBJ containing the debug information. 

If you then do a link using neither of the options to include debug informa¬ 
tion (/DE or /CO), you will find that the linker isn’t smart enough to put the 
debug information into the executable. The Debug Information Offset and 
Size field, as displayed by EXEHDR. EXE, will be blank (Os) and the debugger 
will operate only in assembly language mode. You will not be able to see 
the source code, and any debugging will be extremely difficult. 

If you instead link with either the /DE or /CO option to include the debug 
information, you will find that the debug information does indeed get copied 
from the . OB] into the executable and the . EXE file will be larger. The table 
and length field are set, and the debugger will now show you the source and 
line numbers. 
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63 Down and Dirty Debugging 

When IBM built OS/2, it built all the pieces in individual files. A couple 
of the files, the kernel (0S2KRNL) and the loader (0S2LDR), are key parts 
of the system. Sometimes it is necessary for a programmer to debug code 
(maybe even operating system code) right down into the heart of the kernel 
or loader. This could happen for example, when you are writing a device 
driver or debugging the system or loader itself. 

As part of the build process, IBM also produces special debug versions of 
these two files that contain code to facilitate debugging at this level. OS 2 KRNL, 
0S2LDR, along with symbol files, (which we’ll talk about in a minute) and 
a terminal program constitute what is commonly referred to as the kernel 
debugger. The kernel debugger (KDB for short) is level sensitive. That 
means that it must match the system level exactly to be of any use to you. 
If you have the General Availability level of OS/2 Warp, you must have the 
KDB version that matches it. If you are running on a beta version, it has its 
own KDB. 

The kernel debugger is a powerful tool that allows you access to virtually 
all parts of the operating system. In the proper hands, it is probably the most 
powerful debugger available. However, it is the most user unfriendly tool 
you will ever run into. This is partly because of its complexity, and largely 
because documentation on its use is scarce and difficult to read. The OS/2 
Warp Toolkit has some updated documentation, but you will still find it fairly 
difficult to use and you may want to try other methods first. While it is pos¬ 
sible to do application debugging using the kernel debugger, fortunately for 
application developers, debuggers such as IPMD and CodeVi ew are excellent 
and do the job quite well. 

The kernel debugger works with symbol files which we alluded to a mo¬ 
ment ago. These are special files created by a combination of the linker . MAP 
files (/MAP option) and a program in the Toolkit called MAPSYM. EXE. 

MAPSYM. EXE takes the . MAP files generated by the linker and generates 
. SYM files from them. The . SYM files are what the kernel debugger uses to 
locate symbols in the code it is debugging. If you install the kernel debugger 
you will find that, in addition to the debug versions of 0S2KRNL and 0S2LDR, 
you get a whole bunch of . SYM files. These were generated to match the 
debug version of the kernel when it was built by IBM. 

What you actually do when you install the kernel debugger is replace 
the normal (non-debug) versions of 0S2KRNL and 0S2LDR with the debug 
versions, put the . SYM files in the proper directories, and then attach a terminal 
via the communications port. That terminal, under control of a terminal 
emulator, becomes the output device for the debugger. 

That’s about all we’re going to say about debugging. The debuggers all 
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come with user’s guides, and they provide samples that will teach you all 
you need to know to get started using them. The debugger that comes with 
C Set++ has an online tutorial that takes you through all the 
screens, settings and options. The best way to become familiar with any 
debugger is to use it. 


6.4 OS/2 and its DLLs 

The following is a brief discussion of how OS/2 resolves some of its system 
calls. Programmers who write to the OS/2 operating system are sometimes 
baffled by how it’s done because of the various DLLs and libraries that are 
included. The following discussion should explain something about it for 
those of you who may be interested. 

What we’re talking about here is what happens when you issue calls to OS/2 
from your program and how those calls find the proper piece of executable 
code. When a program calls an OS/2 function, there is some code somewhere, 
probably in a DLL or maybe in the kernel, that is to be executed. Where 
that piece of code is located, is not straightforward in all cases. The system 
is designed so that the programmer does not have to know where each and 
every function “lives” in order to use that function. 

Some calls are resolved by the loader (imported) as calls to code in the 
various DLL binaries (e.g., D0SCALL1.DLL or PMWIN.DLL), and there are 
some calls that resolve to callgates into the OS/2 kernel itself. When a 
program or DLL is loaded, the loader looks at some of the information 
in the header (which we talked about in the last chapter) to find out what 
additional functions (imports) the loading program needs. Unless the loader 
can locate all the functions (the DLLs that contain functions to be imported), 
the program won’t run. 

Many kernel calls are resolved to exports from D0SCALL1.DLL to allow 
for error checking and any other manipulation before entering the kernel 
(via a callgate) to execute the actual worker routine. These worker routines 
in the kernel are usually 32-bit code. What this really means is that when 
you link your object modules with one of the import libraries (OS2286. LIB, 
OS2386. LIB or DOSCALLS. LIB) your executable will, in many cases, be 
importing from DOSCALLl.DLL which may in turn (through a callgate) be 
making a call to the kernel. 

Some calls are completely implemented as user level (ring 3) code in the 
D0SCALL1 □ DLL module itself and never enter the kernel. However, there are 
many calls that go to the kernel (via a callgate) and all the error checking is 
done at the kernel level (ring 0). 
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There are also many calls that end up being forwarded to other DLLs. 
The reason for all this forwarding, as we said before, is to isolate the OS/2 
application writer from having to know where each and every function exists. 
You should remember our discussion in chapter four about forwarders and 
FWDSTAMP. EXE. If you take a look in the 0S2\DLL directory, you will see 
how many DLLs there are and can begin to appreciate the thought that went 
into this scheme. 

One might well ask: “But how do all these things happen-and if the ap¬ 
plication loader is doing all the work, why bother with the OS2286.LIB, 
OS2386. LIB and DOSCALLS. LIB?” A fair question. 

Let’s look at DOSCALLS. LIB first. It provides backward compatibility 
with .OBJs from previous versions of OS/2. It contains information about 
functions that start with “DOS” as well as those beginning with “VIO”, “MOU” 
or “KBD”, in other words, the basic system and subsystem calls. These entries 
will point to DLLs contained in the 0S2\DLL directory. Some of these DLLs, 
such as VIOCALLS.DLL, are no longer used by OS/2 2.x and later. That’s 
not to say they aren’t there, just that the programmer must know to link with 
DOSCALLS. LIB to get to some of them. 

However, DOSCALLS. LIB does nor contain any code! It is an import library, 
and all it contains are relocation (fixup) records that say where (which DLL) 
the function should be imported from and usually what ordinal number to 
use it with. So if you are linking an OS/2 1 .x type of program and link with 
DOSCALLS. LIB, you will be “pointed to” the correct place in OS/2 2.x. 

The OS2286. LIB and OS2386. LIB modules contain all those references 
that DOSCALLS. LIB contains plus things starting with “WIN”, “DRG”, “DDF”, 
“Gpi”, “prp” ? “wp” and all the other things that are supplied from modules 
other than D0SCALL1.DLL and the 0S2KRNL. Again, no code is provided, just 
information needed to resolve the symbol to a function address at load time. 
They are, as we discovered earlier, import libraries. OS2286. LIB is used if 
you are linking a 16-bit program, OS2386. LIB for 32-bit. 

When you use the linker to create an application, you supply it with some 
.0B3 files and the names of the libraries to use when resolving calls to the 
system or other resources. There are libraries, usually supplied with the 
compiler, that contain code and data for standard C functions like pri ntf () 
and fopenC). If we take a look at an . EXE with EXEHDR.EXE we will find 
that there are many functions included, most of which we did not call in our 
source code. These are calls required to implement the functions in the C 
libraries. 
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Experiment 

Take any executable and run 

exehdr.exe -v > filename.out 
against it. Use your editor to take a look at the import table in the 
output. You will find quite a few imports. Some may be named some¬ 
thing like DOSCALLS. 348. These are imports from DOSCALLS. DLL, 
or perhaps the kernel itself. The 348 is the ordinal as discussed above. 
To find out exactly what call is being made, look in the BSEORD. H file. 
It maps the ordinal to the name of the call. (In this case it would be 
Dos32QuerySysInfo). Figure 6.1 is a part of the EXEHDR.EXE out¬ 
put we ran against SMP1.EXE, our simplest sample. We have added 
the call names as defined in BSEORD. H. 


6.5 16-bit vs. 32-bit DLL Operation 

We have not said too much about 16-bit versus 32-bit operation until now. 
These next few paragraphs are/were true with the earliest versions of OS/2 
2.x. Our reason for even mentioning these operations is to try to clarify a 
few things you will see if you are still using programs written for OS/2 1.x 
or an early version of 2.x. 

DLLs can contain either 16-bit objects, 32-bit objects or a combination of 
both. There are some API calls that are a legacy from the 16-bit versions of 
OS/2. In OS/2 V2.x we sometimes have both 16-bit and 32-bit versions of 
the APIs present at the same time. 16-bit and 32-bit code are arranged in 
memory differently, and items such as pointers have to be corrected when 
calling one type from the other. This fact gave rise to the concept of thunks. 


Our understanding is that “thunk” is an acronym for “THing UNder 
the Kover.” 


When your program makes a call to a routine in a DLL that is of the opposite 
type, (e.g., 32-bit program calling 16-bit worker function), the thunk code 
takes care of the conversions before you actually enter the worker code. 
This conversion is accomplished with the help of the header files and import 
libraries that are part of the OS/2 Toolkit. 

The name of the DLL function can be a hint as to what type it is. In order to 
support older 16-bit applications as well as newer 32-bit ones, IBM came up 
with a naming convention that aims to make life as simple as possible for the 
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imp NLS.6 <- 

imp DOSCALLS.348 <- 

imp DOSCALLS.224 <- 

imp DOSCALLS.296 <- 

imp DOSCALLS.234 <- 

imp DOSCALLS.299 <- 

imp DOSCALLS.304 <- 

imp DOSCALLS.312 <- 

imp DOSCALLS.378 <- 

imp DOSCALLS.331 <- 

imp DOSCALLS.282 <- 

imp DOSCALLS.356 <- 

imp DOSCALLS.304 <- 

imp DOSCALLS.378 <- 

imp DOSCALLS.256 <- 

imp MSG.6 <- 

imp DOSCALLS.282 <- 

imp DOSCALLS.224 <- 


Dos32QueryDBCSEnv 

Dos32QuerySysInfo 

Dos32QueryHType 

Dos32ExitList 

Dos32Exit 

Dos32Al1ocMem 

Dos32FreeMem 

Dos32GetInfoBlocks 

Dos32SetSignalExceptionFoc 

Dos32CreateMutexSem 

Dos32Write 

Dos32RaiseException 

Dos32FreeMem 

Dos32SetSignalExceptionFoc 
Dos32SetFi1ePtr 
Dos32T rueGetMessage 
Dos32Write 
Dos32QueryHType 


FIGURE 6.1 

SMP1.EXE Import Table. 


programmer. If there is some worker code that is 16-bit being called by an 
application, that entry point should be declared (according to the convention 
and for example only) something like DosDoMagicO in the header files. 
Any 32-bit application that wants to call the function needs to enter at a 32- 
bit entry named (for example only again) Dos 32DoMagi c () and at that entry 
will be a “thunk” that takes care of the transition from 32-bit entry point to 
the 16-bit worker code. 

If the situation is reversed, in that the worker code is 32-bit, then the 
names are changed in the other direction, e.g., Dosl6DoMagi c(), and the 
“thunk” code is for the 16-bit entry point. A point to keep in mind: with 
each successive version of OS/2, there will be less and less 16-bit worker 
code in the system so, a lot of these quirks will eventually disappear. At this 
writing, quite a few have gone already. 

There are some exceptions to the discussion above. Most common is when 
there are two versions of a function present such as Dos 16C reate. . . () and 
Dos32Create...(). This is not a problem, since the header files provided 
with the Toolkit and compiler have #def i ne statements that take what the 
programmer thinks is the name and alter it to what is actually in the .LIB and 
.DLL files. 

When you link your 16-bit program, you link with OS2286. LIB, and when 
you link your 32-bit program, you link with OS2386.LIB. By calling the 
function with the correct name (Dosl6. . . or Dos32. . .) and linking with 
the appropriate library, you will be pointed to the proper DLL entry point. 
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This has been an attempt to simplify a very complex operation. We would 
suggest you list out (using LIB. EXE) the OS2286.LIB, OS2386.LIB and 
DOSCALLS. LIB libraries and take a look at the actual function names. Then 
browse through the header files in T00LKIT\H and compare one against the 
other. 

As we mentioned in the previous paragraphs, it is possible to call 16-bit 
functions from 32-bit code and vice versa, there doesn’t seem to be a practical 
reason why somebody would want to try to get to 32-bit calls from a 16-bit 
program. SMP7 and SMP8 are examples of each case. SMP7 shows how to 
call a 32-bit function from a 16-bit program; SMP8 shows the same program 
implemented as a 32-bit program calling a 16-bit function. 


6.6 Calling Between 16-bit Code and 32-bit Code 

SMP7 and SMP8 are examples of calling a 32-bit DLL from a 16-bit program 
(SMP7) and vice versa (SMP8). They are done entirely in C and show how 
thunking makes it possible. SMP7 and SMP8 are a little different than the 
previous samples in that they require both a 16-bit compiler and a 32-bit 
compiler to build, and they do make OS/2 calls. The source and makefiles 
are included on the sample diskette so you can take a look at them even if 
you don’t have two compilers. Executables are also included so you can run 
them on OS/2. 


NOTE: We used Microsoft C 6.0 to create the 16- bit samples. 
Notice also that we used the large model, multithread library, 
(LLIBCMT. LIB). Other libraries can be used, but you will have to 
modify the makefile. 


Both samples are essentially the same: we have an executable program 
calling a function that resides in a DLL of the opposite type. We used a 
simple DosBeep as the target function. 

Since SMP7, 16-bit program calling 32-bit DLL, is the least used, let’s 
discuss that and we’ll leave SMP8 up to you. 

We need a simple interface from which we can use functions contained in 
dynamic link libraries. To do this, the function (Cal 1 MakeSomeNoi se) con¬ 
tained in FILTER. DLL will serve as our interface into the target DLL where 
the function we are actually trying to execute (MakeSomeNoi se) resides. 




(5.7. MARKEXE 


87 


By declaring Cal 1 MakeSomeNoi se as _Farl6 _Pascal, the 32-bit com¬ 
piler will create a 32-bit function with a 16-bit entry sequence (thunk), which 
will allow it to be called by our 16-bit program. 

Because of the 16-bit entry, we can now call the interfacing function, 
Cal 1 MakeSomeNoi se, from our 16-bit program, and Cal 1 MakeSomeNoi se 
in turn can call functions in the 32-bit DLL in the standard fashion. By 
creating the import library, FILTER. LIB, and using it when we link the 16- 
bit executable, our executable is able to call the 32-bit function at its 16-bit 
entry point. 

In our sample, FILTER.DLL loads DLL32BIT.DLL via DosLoadModule 
and then uses DosQueryProcAddr to get the address of the MakeSomeNoi se 
function which it then calls. 

The source code for the FILTER.DLL and the DLL32BIT.DLL are provided 
along with the makefiles so that you can experiment with the code and re¬ 
compile it to experiment if you wish. If you make SMP7, you will receive a 
warning (L4008) from the linker because it recognizes that we are calling a 
32-bit function with 16-bit code. This warning can be ignored. 

SMP8 is the same as SMP7 with the exception that this time we call from 
32-bit code to a 16-bit DLL. There are other ways of accomplishing the same 
thing. These samples are designed to show you one fairly simple method. 

To build 16-bit executables, you will need a 16-bit compiler. We used 
Microsoft C version 6.0. 


6.7 MARKEXE 

MARKEXE. EXE is another tool in the OS/2 Toolkit. It is used to display or 
change the program type of an OS/2 executable. The program type deter¬ 
mines what type of sessions a program can run in. MARKEXE. EXE does this by 
changing the information contained in a couple of the fields in the executable 
header. You can, for example, change a program from WIND0WC0MPAT to 
N0TWIND0WC0MPAT which means that a program that ran in an OS/2 window 
will now only run in an OS/2 full screen session. 

MARKEXE. EXE can also be used to add or remove long file name support 
and to set or reset per-process DLL initialization and termination options. 

The use of MARKEXE. EXE is fairly straightforward, and the online docu¬ 
mentation contains details of its use. It is used infrequently, but it can effect 
the executable header, so it’s worth at least mentioning. 
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6*8 Surfing the Header Files 

Another good tool to have is one that will allow you to search for text strings 
in a file or groups of hies. The Seek and Scan Files applet (PMSEEK. EXE) 
that comes with OS/2 or the GREP sample that comes with the WorkFrame 
can be used for this and can be a big help when looking through the header 
hies. 

A little trick to use is to run LIB. EXE against the library hies such as 
OS2 386. LIB and OS2286. LIB and create List hies. You can then use GREP, 
PMSEEK. EXE, or your favorite text editor to scan for the name of a function 
you are interested in. That way you can determine the exact name of the 
function as well as how it is dehned in each of the libraries. 

These programs are also a big help when looking through Toolkit header 
hies. You can change to the \T00LKIT\H directory and GREP all headers for 
whatever information you want. This is an easy way to hnd ordinals, macros, 
etc. 


63 Summary 

• Debugging information must be explicitly included in your programs 
by setting options for the compiler and linker. 

• Debuggers interpret the information in the source and . EXE to assist 
us in debugging. 

© The kernel debugger (KDB) is available from IBM and is extremely 
powerful, if difficult to use. 

• The import libraries, headers, thunking and the concept of forwarders 
isolate the programmer from having to know details of DLL contents 
when calling OS/2 functions. 

® There is a mixture of 16-bit and 32-bit functions in OS/2. Thunking 
enables us to get to any function from any program. 

• There are many tools available to help us explore. 

Hopefully, you have had a chance to use DECODE. EXE. We wrote it as an 
adjunct to the material in this book. It can be a very useful tool. In the next 
chapter we show you how it is put together and we provide all the source 
code so that you may modify it to suit your individual needs. 



A Few Last Words 


When we first started putting together the information for this book, we found 
a lot of the things we needed existed, but there was one thing that didn’t exist. 
If it did, we couldn’t find it. That was a program that was able to take an 
object file (.OBJ) and interpret what records it was made up of. The early 
chapters go into some detail on the subject so we wrote DECODE. EXE. 

With an editor, DECODE. EXE and EXEHDR. EXE, you should be able to look 
at a program in any stage of its completion. Use the editor for source code, 
DECODE. EXE for the .OBJs and . LIBs and EXEHDR. EXE for the final execu¬ 
table. With these tools and this book, you have a wealth of information 
about OS/2 executable file formats at your disposal. 


7.1 BECOOE.EXE 

The decoder program is not very sophisticated nor is it very elegant. We 
have put more options in it than most people will use, but it does work, and 
it is a good companion to the material in this book. It is a text mode program 
rather than a Presentation Manager application for portability. Because of 
its relative simplicity and exclusive use of standard C functions, it should be 
easy to modify and/or port to any standard C/C++ compiler. 

DECODE. EXE is made up of four basic functions. The main function reads 
the keyboard for options, creates output files, allocates storage for the actual 
decoding, calls the other routines of the program, and finally performs some 
cleanup. It is farily straighforward. Figure 7.1 shows the source for main(). 

The first routine called by mai n () is ReadFi 1 e () which actually reads the 
subject file into the memory block set up by mai n (). We could have done 
the decoding by reading the file and positioning the file pointer, but because 
of OS/2’s virtual storage, it was more efficient and quicker to load the entire 
file into memory and operate on it there. 

Readf i 1 e () checks to see that the file reads correctly and checks the first 
byte to see if we are indeed looking at a valid . OBJ or . LIB file. 
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void main(int argc, char *argv[]) 

{ 

/* 

Vari abl es 

*/ 


char Fi1eName[100]; 
long Bytes; 

unsigned char *BaseAddress; 
long BytesRead; 
long InCount; 
short i ; 

char Rec[15], Dump[15]; 
OutFlag = DumpFlag = 0; 


/* 

Get basename of input file and create output file names 

V 


if(argv[l] != NULL){ 

for(i = 0; i <= strlen(argv[l]); i++) 

FileName[i] = toupper(argv[l][i]); 

} else{ 

fprintf(stderr, 

"\nFormat: DECODE xxx.yyy [/s] [/d] \n"); 

return; 


for (i = 0 ; argv[l][i] != i++){ 

if(argv[1][i] ! = ’\0’){ 

Dump[i] = toupper(argv[l][i]); 

Rec[i] = toupper(argv[l][i]); 

} else { 

fprintf(stderr, 

"\nFormat: DECODE xxx.yyy [/s] [/d]\n"); 

return; 

} 

} 


FIGURE 7.1 
BECODE.EXE main() 
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Rec[i] = ’\0 5 ; 

Dump [i] - ’\0’; 
strcat(Rec,".REC"); 
strcat(Dump, ".DMP"); 


if((InFi1e = fopen(FileName, "rb")) == NULL){ 

fprintf(stderr, "\nlnvalid File Name, re-enter a valid" 
" .OBJ fi1e\n"); 

return; 

}; 


fseek (InFile, OL, SEEK_END); /* Determine file size */ 

InCount = ftel1(InFi1e); 

fseek (InFile, OL, SEEK_SET); /* Return to beginning of file * 

/* Get storage to match file size */ 

if((BaseAddress = mal1oc(InCount)) == NULL){ 
fprintf(stderr, "Storage Allocation error"); 
return; 

}; 

for( i = 1; i <= (argc -1); i++){ /* Screen output desired? */ 

if(!strncmp(argv[i], "/s" , sizeof(argv[i])) || 

(!strncmp(argv[i], M /S", sizeof(argv[i])))) 

OutScrn = 1; 

if(!strncmp(argv[i], "/d" , sizeof(argv[i])) || 

(!strncmp(argv[i], M /D", sizeof(argv[i])))) 

DumpFlag = 1; 

}; 

/* Read in the .OBI */ 

Bytes = ReadFi1e(InCount, InFile, BaseAddress); 

if (Bytes){ 

if(DumpFlag){ 

if((DumpFile = fopen(Dump, "w+")) == NULL){ 

fprintf(stderr, "Could not open %s\n", Dump); 
return; 

} 

} 


FIGURE 7.1 (continued) 
DECODE.EXE main() 
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if((RecFile = fopen(Rec , "w+ M )) == NULL){ 

fprintf(stderr, "Could not open %s\n", Rec); 
return; 

} 


/* 

Interpret file using the pointer to the location in memory 
where it was read in to 

V 

IntFile(BaseAddress); 

/* OutFlag on indicates a full .OBJ dump */ 

if(DumpFlag){ 

OutFlag = 1; 

PrintFi1e(InCount, BaseAddress, 0); 

OutFlag = 0; 

}; 

printf("\n\nThe file %s contains %ld bytes in " 

"%d records.\n\n", 

FileName, Bytes, RecCount); 

printf("Examine %s and %s with a text editor " 

"for details.\n\n", 

Rec, Dump); 

printf("(NOTE:%s will not exist unless you used " 

" the /d option.) 

\n\n",Dump); 

}; 

fclose(InFi1e); /* Clean Up */ 

fclose(DumpFi1e); 
fclose(RecFile); 
free(BaseAddress); 
return; 


FIGURE 7.1 (continued) 
BECODE.EXE main() 
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Library files are made up of multiple . OBJ files, and therefore many times 
they are quite large. DECODE.EXE has no problem handling large files, but 
doing so can be very time consuming. Therefore, we included a couple of 
selections to allow the user to look only for certain types of records. We 
purposely require the user to enter the entire name of the record types to 
search for in . LIBs and the program defaults to an empty output file to avoid 
executing DECODE. EXE for a long time. 

THEADR records mark the beginning of each object in a library file. By 
inspecting THEADR records, the name of the source file for each of the objects 
can be determined. 

COMENT records in import libraries can be used to determine ordinal num¬ 
bers. The EXPDEF (Export Definition) record, Class AO, subtype 2, has the 


format: 




<Byte> <Byte> 

<variable> 

cvariable> 

<2 Bytes> 

02 Export Flag 

Exported 

Internal 

Ordinal 

Name 

Name 



By scanning an import library for COMENT records and looking at the pro¬ 
duced output, it is not difficult to match the internal function name to its 
ordinal (in hexadecimal) and vice versa. 

Figure 7.2 is the source for the ReadFileO routine. Again, it is fairly 
straightforward and uses only standard C functions. It returns the actual 
number of bytes read. 

IntFi 1 e () is the routine that actually does the decoding of the input file. 
It lines itself up at the very first record of the file and walks through the 
records one at a time. It analyzes the first byte of each record and the switch 
statement sets the record type. 

In order to determine where one record ends and the next begins, it is 
necessary to calculate the record lengths. The bytes of the record length 
field are reversed so we had to do some bit shifting to get the correct length. 

. LIB files add padding characters from the MODEND record to start the next 
object on a page boundary. The page length is obtained from the LIBSTT 
record and used to calculate the number of bytes from a MODEND record to 
the beginning of the next object record. 

Figure 7.3 shows the source for the IntFi 1 e () routine. 

The fourth and final routine of DECODE. EXE is Pri ntFi 1 e (). This routine 
writes the outout to the output files and will also write to the screen if the /S 
option was used. It formats the output and substitutes for unprintable 
ASCII characters. This routine also produces the record separators to make 
reading the output files easier. As usual, only standard C functions were 
used. Figure 7.4 is the source for Pri ntFi le(). 
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long ReadFi1e(long int 
unsigned 


{ 


InCount, FILE *InFile, 
char *BaseAddress) 


long BytesRead; 
i nt i ; 


BytesRead = fread(&(*BaseAddress), sizeof(char), 
InCount, InFile); 


if(BytesRead == 0){ 

fprintf(stderr, "Read Fail on Input file\n M ); 
BytesRead = 0; 

} 


/* Check to see if this is valid .OBI or .LIB file */ 

if((*BaseAddress != 0x80) && (*BaseAddress != 0xF0)){ 
fprintf(stderr, "\nNot a valid .OBI or .LIB file\n"); 
BytesRead = 0; 
return BytesRead; 

} 

if(*BaseAddress == 0xF0){ 


printf("Sinee this is a .LIB file, please enter the type 
"of record you\n\wish to scan for. Press enter " 
"for no records. Selecting \"ALL\" may cause\n" 
"the program to run for a long time.\n\n"); 


printf("Choices are:\n\n" 

"\nTHEADR <Gives Source/.OBI module names>" 

"\nC0MENT <Can help determine which DLL/Ordinal>" 

"\nALL <0utputs all records, can take time>" 

"\n<Enter> <Default- No output files produced>\n\n\n"); 


FIGURE 7.2 

DECODE.EXE ReadFileQ 
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gets(ScanType); 

for (i = 0 ; i <= strlen(ScanType); i++) 
ScanType[i] = toupper(ScanType[i]); 


Show =0; 

if (!strcmpC'THEADR", ScanType)) 

Show = 0x80; 

else if (!strcmp("C0MENT", ScanType)) 
Show = 0x88; 

else if (!strcmp("ALL M , ScanType)) 
Show = OxFF; 

} 

pri ntf("\n\n\n"); 
return BytesRead; 

} 


FIGURE 7.2 (continued) 
DECODE.EXE ReadFileQ 
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void IntFi 1 e(unsigned char *BaseAddress) 

{ 

char RecType[10]; 
short ThisLen, PageLen; 
char *NextRec; 
short i; 
char *here; 
char goodbye = 1; 
unsigned long Offset = 0; 
short Diff = 0; 


/* 

The following code steps through the records one at a 
time. Since the length field has the low order and high 
order bytes reversed, we have to do the left shift 

V 


RecCount = 0; 
whi1e(goodbye){ 

ThisLen = (*(BaseAddress + 2) «8) + 
(*(BaseAddress 4 1) + 3); 
NextRec = (BaseAddress) + (ThisLen); 


switch(*BaseAddress) 

{ 

case THEADR: 

strcpy(RecType, "THEADR"); 
break; 


/* 

Library files are padded in the MODEND record to ensure all 
modules begin on a page boundary. The page length is 
determined in the LIBSTT record. 

V 

case MODEND: 
case M0DEND16: 

strcpy(RecType,"MODEND") ; 
if(InLib){ 

Diff = PageLen - ((OffSet + ThisLen) % PageLen); 
if((Diff != PageLen) && (Diff != 0)){ 

ThisLen += Diff; 

NextRec += Diff; 

}; 

}; 

i f (! InLi b) 

goodbye = 0; 
break; 


FIGURE 73 
DECODE.EXE IntFileQ 



7.1. DECODE.EXE 


97 


The length field of the LIBST record determines the 
page length. This is used to ensure all modules begin 
on a page boundary. Padding is performed on the MODEND 
record to get to the next page boundary. 

*/ 

case LIBSTT: 

strcpy(RecType, "LIBSTT"); 

PageLen = ThisLen; 

InLib = 1; 

LibFlag = 1; 
break; 


/* 

The LIBSTP record marks the boundary between the object 
modules and the dictionary. This program ends at this 
point and does not attempt to decode the dictionary. 

*/ 

case LIBSTP: 

InLib = 0; 

strcpy(RecType, "LIBSTP"); 

goodbye = 0; 

break; 

case LHEADR: 

strcpy(RecType,"LHEADR"); 
break; 

case COMENT: 

strcpy(RecType, "COMENT"); 
break; 

case EXTDEF: 

strcpy(RecType, "EXTDEF"); 
break; 


case PUBDEF: 
case PUBDEF16: 

strcpy(RecType,"PUBDEF"); 
break; 


FIGURE 7.3 (continued) 
DECODE.EXE IntFileQ 
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case LINNUM: 
case LINNUM16: 

strcpy(RecType,"LINNUM"); 
break; 

case LNAMES: 

strcpy(RecType,"LNAMES"); 
break; 


case SEGDEF: 
case SEGDEF16: 

strcpy(RecType, "SEGDEF"); 
break; 

case GRPDEF: 

strcpy(RecType,"GRPDEF"); 
break; 


case FIXUPP: 
case FIXUPP16: 

strcpy(RecType, "FIXUPP"); 
break; 


case LEDATA: 
case LEDATA16: 

strcpy(RecType, "LEDATA"); 
break; 


case LIDATA: 
case LIDATA16: 

strcpy(RecType, "LIDATA"); 
break; 

case COMDEF: 

strcpy(RecType, "COMDEF"); 
break; 


FIGURE 7.3 (continued) 
DECODE.EXE IntFile() 
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case BAKPAT: 
case BAKPAT16: 

strcpy(RecType, "BAKPAT"); 
break; 


case LEXTDEF: 
case LEXTDEF16: 

strcpy(RecType, "LEXTDEF"); 
break; 


case LPUBDEF: 
case LPUBDEF16: 

strcpy(RecType, "LPUBDEF"); 
break; 

case LCOMDEF: 

strcpy(RecType, "LCOMDEF"); 
break; 


case COMDAT: 
case COMDAT16: 

strcpy(RecType, "COMDAT"); 
break; 


case LINSYM: 
case LINSYM16: 

strcpy(RecType, "LINSYM"); 
break; 

case ALIAS: 

strcpy(RecType, "ALIAS"); 
break; 


case NBKPAT: 
case NBKPAT16: 

strcpy(RecType, "NBKPAT"); 
break; 


FIGURE 7.3 (continued) 
DECODE.EXE IntFileQ 
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default: 

strcpy(RecType, "UNKNOWN"); 

printf("\n\t<***Unknown record detected at Offset" 
%1u***>\n\n", Offset); 

break; 

} 

RecCount += 1; 
if (Show == ALL) 

LibFlag = 0; 

if ((ILibFlag) || (*BaseAddress == Show)){ 
if(OutScrn) 

printf("Record # %d\t\tRecord Type = %s\n" 
"Offset = %1u\t\tLength = %d\n\n", 
RecCount, RecType, Offset, ThisLen); 

fprintf(RecFile, 

"Record # %d\t\tRecord Type = %s\n0ffset =" 
"%lu\t\tLength = %d\n\n", 

RecCount, RecType, Offset, ThisLen); 

if(ferror(RecFile)){ 

printf("Write Failure on %s," 
ending program.\n",RecFi1e); 
exit(EXIT_FAILURE); 

} 

PrintFile(ThisLen, BaseAddress, Offset); 

Offset += ThisLen; 

BaseAddress = NextRec; 


} 

return; 


FIGURE 73 (continued) 
DECODE.EXE Intfile() 







7.1. DECODE.EXE 


101 


void PrintFile(short count, unsigned char *BaseAddress, 
unsigned long Offset) 


{ 


FILE *OutFi1e; 
short i; 


i = 0; 

if(OutFlag) /* OutFlag determines which output file */ 
OutFile = DumpFile; 
el se 

OutFile = RecFile; 


if(ferror(OutFile)){ 

printf("Write Failure on %s, ending program.\n M ,OutFile); 
exit(EXIT_FAILURE); 

} 

for (i =0 ; i < count; i++){ 

ifC i % 16 ==0){ 

if(OutScrn) 

printf("\n%061u ", (OffSet+i)); 
fpri ntf(OutFile,"\n%061u ", (OffSet+i)); 

if(ferror(OutFile)){ 

printf("Write Failure on %s, 

"ending program.\n",OutFile); 
exit(EXIT_FAILURE); 

} 

} 

if(OutScrn) 

printf("%02x ", *(BaseAddress+i)); 
fprintf(OutFi1e,"%02x ", *(BaseAddress+i)); 
if(ferror(OutFi1e)){ 

printf("Write Failure on %s, ending program.\n", 
OutFile); 

exit(EXIT_FAILURE); 

} 

} 


FIGURE 7.4 

DECODE.EXE PrintFile() 
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if(OutScrn) 

printf("\n"); 
fprintf(OutFile,"\n"); 
if(ferror(OutFile)){ 

printf("Write Failure on %s, ending program.\n n 5 
OutFi1e); 

exit(EXIT_FAILURE); 

} 


/* 

The following is almost exactly like the beginning 
of the function except that it produces the ASCII printout. 
Each character is checked to see if it is printable, if not, 
a is printed. This will make the output much easier to 

scan for strings. 

V 


for (i =0 ; i < count; i++){ 
if ( i % 16 == 0){ 
if(OutScrn) 

printf("\n%061u ”, Offset + i); 

fprintf(OutFile, "\n%061u ", Offset + i); 

if(ferror(OutFile)){ 

printf("Write Failure on %s, ending " 

"program.\n",OutFile); 

exit(EXIT_FAILURE); 

} 

} 

i f(i spri nt(*(BaseAddress+i))){ 
if(OutScrn) 

printf("%02c ", *(BaseAddress+i)); 
fprintf(OutFile,"%02c ", *(BaseAddress+i)); 
if(ferror(OutFi1e)){ 

printf("Write Failure on %s, " 

ending program.\n",OutFi1e); 

exit(EXIT_FAILURE); 

} 


FIGURE 7 A (continued) 
DECODE.EXE PrintFile() 
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} else{ 

if(OutScrn) 

printf(".. "); 

fprintf(OutFi1e, "); 

if(ferror(OutFile)){ 

printf("Write Failure on %s, " 

" ending program.\n",OutFi 1 e); 
exit (EXIT_FAILURE); 

} 

} 

} 


} 


if(!OutFiag){ /* Record separator */ 

if(OutScrn) 

printf("\n\n-\n\n"); 

fprintf(OutFile, "\n\n-\n\n") ; 

} 


FIGURE 7.4 (continued) 
DECODE.EXE PrintFileO 
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As we said previously, DECODE. EXE is not very elegant, but it should be 
easy to modify for your own purposes. Feel free to experiment. The complete 
source and makefile are on the accompanying diskette. 


7.2 Now Go and Play 

In this book, we have examined the makeup of an OS/2 executable file 
from its inception right through to the point where it is loadable and runable 
by the operating system. Our intention was not to teach all there is to know, 
merely to introduce you to some of the concepts and details. 

We have seen no other books commercially available that talk about these 
subjects. That is why we decided to write this one. We have covered a lot of 
material but we have still only scratched the surface, this was an introduction. 
It is our hope that we have given you a good foundation. For those readers 
who care to dig even deeper, there are, as we have noted, more in depth 
publications on some of the topics. 

Flave fun exploring! 



Appendix: The 16/32-Bit Object Module 
Format 


Record Format: 

All object records conform to the following format: 


1 byte 

2 byte 

< variable length> 

1 byte 

Record Type 

Record Length 

Record Contents 

Chk Sum 



< record length in 

i bytes > 


FIGURE 7.5 

Standard object module record format. 

The Record Type field is a 1-byte field containing the hexadecimal num¬ 
ber that identifies the type of object record. The format is determined by the 
least significant bit of the Record Type field. Note that this does not gov¬ 
ern Use32/Use 16 segment attributes; it simply specifies the size of certain 
numeric fields within the record. An odd Record Type indicates that 32-bit 
values are present. An even Record Type indicates that those fields contain 
16-bit values. The fields affected are described with each record. 

An entire record occupies Record Length + 3 bytes. The record length does 
not include the count for the record type and record length fields. Unless 
otherwise noted within the record definition, the record length should not 
exceed 1024 bytes. 

The Record Contents are determined by the record type. 

The Chk Sum field is a 1-byte field that contains the negative sum (modulo 
256) of all other bytes in the record. The byte sum over the entire record, 
ignoring overflow, is zero. 
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NOTES: 

LINK386 ignores the value of the Chk Sum byte. 


Frequent Object Record Subfields 

The contents of each record are determined by the record type, but certain 
subfields appear frequently; the format of such fields is described next. 

Names 

Name strings are encoded as an 8-bit unsigned count followed by a string 
of “count” characters. The character set is usually some ASCII subset. A 
null name is specified by a single byte of 0 (indicating a string of length 
zero). 

Indexed References 

Certain items are ordered by occurrence, and referenced by index (starting 
index is 1). Index fields can contain 0, indicating not-present, or values from 
1 through 7FFF. The index is encoded as 1 or 2 bytes. 

If the index number is in the range 0-7H, the high-order bit (bit 7) is 0 and 
the low-order bits contain the index number, so the field is only 1 byte long. 
If the index number is in the range 80-7FFFH, the field is 2 bytes long. The 
high-order bit of the first byte in the field is set to 1, and the high-order byte 
of the index number which must be in the range (0-7FH) fits in the remaining 
7 bits. The low-order byte of the index number is specified in the second 
byte of the field. A 16-bit value is obtained as follows: 

if (first_byte & 0x80) 

index_word = (first_byte & 7F) * 0x100 + 

second_byte; 

el se 

index_word = first_byte 
Type Indices 

The type index is treated as an index field when a record is parsed (occupies 
one or two bytes, occurs in PUBDEF, COMDEF, EXTDEF records). They are 
encoded as described under indexed references. 
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NOTE: At present, no type checking is done by the linker. If any link-time 
semantics are defined, that information will be recorded somewhere within 
this document. 

Ordered Collections 

Certain records and record groups are ordered; the ordering is obtained 
from the order of the record types within the file together with the ordering of 
repeated fields within these records. Such ordered collections are referenced 
by index, counting from 1 (index 0 indicates unknown or decline-to-state). 

For example, there may be many L NAMES records within a module and each 
of those records may contain many names. The names are indexed starting 
at 1 for the first name in the first LNAMES record encountered while reading 
the file, 2 for the second name in the first record, etc., and the highest index 
for the last name in the last LNAMES record encountered. 

The ordered collections are: 

• NAMES: ordered by LNAMES record and names within each. Refer¬ 
enced as a Name Index. 

• LOGICAL SEGMENTS: ordered by SEGDEF records in file. Refer¬ 
enced as a Segment Index. 

® GROUPS: ordered by GRPDEF of records in file. Referenced as a 
Group Index. 

• EXTERNAL SYMBOLS: ordered by EXTDEF and COMDEF records 
and symbols within each. Referenced as an External Index (in FIX- 
UPs). 

Numeric 2 and 4 byte fields 

Words and double words (16 and 32 bit quantities) are stored in Intel byte 
order (lowest address is least significant). 

Certain records, notably SEGDEF, PUBDEF, LINNUM, LEDATA, LIDATA, FIXUPP 
and MODEND, contain size, offset, and displacement values which may be 32 
bit quantities for Use32 segments. The encoding is as follows. 

® When the least significant bit of the record type byte is set (i.e., record 
type is an odd number), the numeric fields are 4 bytes. 

® When the least significant bit of the record type byte is clear, the 
fields occupy 2 bytes (16 bit Object Module Format). The values are 
zero-extended when applied to Use32 segments. 
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See the description of SEGDEF records for an explanation of Usel6/Use32 
segments. 


Order of records 

The record order is chosen so that bind/link passes through an object 
module are minimized. This differs from the previous less specific ordering 
in that all symbolic information (in particular, all export and public symbols) 
must occur at the start of the object module. This order is recommended but 
not mandatory. 

Identifier record(s): 

Must be the first record. 

• THEADRor LHEADR 

Records processed by Link Pass one: 

May occur in any order but must precede the Link pass separator if it is 
present. 

• COM ENT class AF providing name of Identifier Manipulator Dynamic 
Link Library (should be near the beginning of the file) 

• COM ENT identifying object format and extensions 

• COM ENT any, other than link pass separator comment 

• LNAMES providing ordered name list 

• SEGDEF providing ordered list of program segments 

• GRPDEF providing ordered list of logical segments 

• TYPDEF (no longer used) 

• ALIAS records 

« PUBDEF locating and naming public symbols 

• LPUBDEF locating and naming private symbols. 

• COMDEF, EXTDEF, LCOMDEF, LEXTDEF records 
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This group of records is indexed together, so External Index 
fields in FIXUPP records may refer to any of the record types 
listed. 

© COMDAT records 

Link pass separator (optional): 

• COMENT class A2 indicating that pass 1 of the linker is complete. 

When this record is encountered, LINK immediately starts Pass 
2; no records after this comment are read in Pass 1. All the 
above listed records must come before this comment record. 
For greater linking speed, all LIDATA, LEDATA, FIXUPP and 
LINNUM records should come after the A2 comment record, but 
this is not required. 

In LINK, Pass 2 begins again at the start of the object module, 
so LIDATA records, etc., are processed in Pass 2 no matter where 
they are placed in the object module. 

Records ignored by link pass one and processed by link pass two: 

May come before or after link pass two: 

• LIDATA or LEDATA records followed by applicable FIXUPP records. 

• FIXUPPs containing THREADS only. 

• BAKPAT and NBAKPAT fixupps. 

© LINNUM and LINSYM providing line number to program code or data 
association. 

Terminator 

• MODEND indicating end of module with optional start address. 
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OBJECT RECORD TYPES 


80H THEABR Translator Header Record 
Description: 

The THEADR record contains the name of the object module. This name 
identifies an object module within an object library or in messages produced 
by the linker. 


1 byte 

2 byte 

1 byte 

< variable length> 

1 byte 

80 

Record 

String 

Name String 

Chk Sum 


Length 

Length 


or 0 


FIGURE 7.6 

THEADR record type definition. 

The String Length byte gives the number of characters in the name string; 
the name string itself is ASCII. This name is usually that of the source 
program (if supplied by the language translator), or may be specified directly 
by the programmer (e.g., TITLE pseudo-op). 

This record must occur as the first object record. More than one header 
record is allowed (as a result of an object bind, or if source arose from 
multiple files as a result of include processing). 

NOTES: 

The name string is always present; a null name is allowed but not recom¬ 
mended (not much information for a debugger that way). 

It is recommended that the module be generated with the full path and 
filename containing the source code. 

The THEADR record must be the first record of the object module. 

More than one header record is allowed (as a result of source from multiple 
files during the include process). 
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82H LHEADR Library Header Record 
Description: 

This record is very similar to the THEADR record. It is used to indicate the 
name of a module within a library file (which has a different organization 
internally than an object module). 

Record format: 


1 byte 

2 byte 

1 byte 

< variable length > 

1 byte 

82 

Record 

String 

Name String 

Chk Sum 


Length 

Length 


or 0 


FIGURE 7.7 

LHEADR record type definition. 

NOTES: 

In LINK, THEADR and LHEADR records are handled identically. 
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88H COMENT Comment Record 
Description: 

The COMENT record contains a character string that may represent a plain 
text comment, a symbol meaningful to a program such as LINK or LIB, or 
some binary coded information that alters the linking process. The comment 
records are actually a group of items, classified by “comment class”. 


1 byte 2 bytes 


88 


Record 


1 byte 

1 byte 

< Record Length - 3 > 

1 byte 

Comment 

Comment 

Commentary byte string 

Chk Sum 

Type 

Class 

(optional) 



FIGURE 7,8 

COMENT record type definition. 


Comment Type 

The comment type byte is bit-significant; layout is: 


< 1 byte > 


NP 

NL 

0 

0 

0 

0 

0 

0 


where 


NP is set if the comment is to be preserved by object bind utilities 
NL is set if the comment is not for display by object bind utilities 
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Comment class and commentary byte string 

The comment class is an 8-bit numeric which conveys information by 
its value (accompanied by a null byte string), or indicates the information 
to be found in the accompanying byte string. The byte string’s length is 
determined from the record length, not by an initial count byte. 

The values in use currently are the following: 

0 Translator 

For translator; may name the source language or translator. Recom¬ 
mended: translator name and version plus optimization level used for 
compilation be recorded here. Other compiler or assembler options 
can be included, although current practice seems to be to place these 
under comment class 9D. 

1 Intel copyright 

Ignored by the linker. 

2 through 9B Intel reserved 

The values from 9C through FF are ignored by Intel products. 

9C MS-DOS version - obsolete 

Ignored by linker. 

9D Memory Model - ignored 

Ignored by linker. 

9E DOSSEG 

Sets the linkers DOSSEG switch. The byte string is null. This record 
is included in the startup module in each language library. It directs 
the linker to use the standardized segment ordering, according to the 
naming conventions documented with DOS, OS/2 and accompanying 
language products. 

9F Library indicator 

The byte string contains a library file name (without a lead count byte 
and without an extension). Can be over-ridden via NOD link switch. 
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AO OMF extensions 

This class consists of a set of records, identified by subtype (first byte 
of commentary string). Values supported by the OS/2 2.0 linker are 

01 IMPDEF 

Import definition record. See IMPDEF section for 
complete description. 

02 EXPDEF 

Export definition record. See EXPDEF section for 
complete description. 

03 INCDEF 

Incremental compilation record. See INCDEF section 
for complete description. 

04 Protected Memory Library 

Relevant to 32 bit DLL’s. This comment record is in¬ 
serted in the object module by the compiler when it 
encounters a compiler option or pragma indicating a 
protected DLL. The linker then sets a flag in the header 
of the executable file (DLL) to indicate that the DLL 
should be loaded in such a way that its shared code and 
data is protected from corruption. 

When the flag is set in the EXE header, the loader loads 
the selector of the protected memory area into the DS 
while performing run-time fixups (relocations). All 
other DLL’s and applications get the regular DGROUP 
selector, which doesn’t allow access to the protected 
memory area set up by the operating system. 

05 LNKBIR 

C++ linker directives record. See LNKDIR section 
for complete description. 

06-FF Reserved for Microsoft. 

NOTE: presence of any unrecognized subtype causes LINKER 
to generate a fatal error. 


A1 Symbolic debug information 

This comment class is now used solely to indicate the version of the 
symbolic debug information. 

The byte string will be a version number (8-bit numeric) followed 
by an ASCII character string indicating the style of symbol and line 
number (LINNUM) information. Current values are 

n 9 ? Cy V 9 CodeView style 
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iVDYX 5 AIX style 
ii, ? HYL 9 IBM PM Debugger 

A2 Link Pass 

This record conveys information to the linker about the organiza¬ 
tion of the file. At present, a single sub-extension is defined. The 
commentary string is 


01 


Optional 


Subclass 01 indicates the start of link pass 2 records; this may be 
followed by anything at all, which will be ignored by the linker (de¬ 
termined from the RecLength). When this comment appears, the 
linker can rest assured that only LEDATA, LIDATA, FIXUPP, LINNUM 
and the terminal MOD END records will occur after this. All other record 
types, plus THREAD fixups, occur before. 


WARNING: It is assumed that this comment will not be present in a 
module whose MODEND record contains a program starting address. 


A3 LIBMOB indicator 

Library module comment record. Ignored by LINK386. 

A4 EXESTR indicator 

Executable Module Identification String 

A commentary string specifying a string to be placed in the executable 
module, but which is not loaded with the load module. 


A6 


INCERR 

Incremental compilation error. See INCERR section for a complete 
description. 


A7 


NOPAD 

No segment padding. Ignored by LINK386. 
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A8 WKEXT 

Weak Extern record. See WKEXT section for a complete description. 

A9LZEXT 

Lazy Extern record. Ignored by LINK386. 

AA PHARLAP 

PharLap Format record. Ignored by LINK386. 

AF IDMDLL indicator 

Identifier Manipulator Dynamic Link Library. See IDMDLL section 
for a complete description 

B2H-BFH 

Unused 

C0H-FFH 

Reserved for user-defined comment classes. 


Notes: 

A COMENT record can appear almost anywhere in an object module. Only 
two restrictions apply: 

• A COMENT record cannot be placed between a FIXUPP record and the 
LEDATA or LI DATA record to which it refers. 

• A COMENT record can not be the first or last record in an object module. 
(The first record must always be a THEADR record and the last must 
always be a MODEND). 
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88H IMPDEF Import Definition Record 
(comment class AO, subtype 01) 

Description: 

This record describes the imported names for a module. 

Record format: 

One import symbol is described; the subrecord format is 


1 

1 

<variable> 

<variable> 

2 or <var> (bytes) 

01 

Ord 

Internal 

Module 

Entry 


Flag 

Name 

Name 

Ident 


FIGURE 73 

IMPDEF record type definition, 
where: 

01 identifies the subtype as an IMPDEF 

OrdFIag is a byte; if zero the import is identified by name. If nonzero, it 
is identified by ordinal. Determines the form of the Entryldent field. 

InternalName in <count, char> string format and is the name used within 
this module for the import symbol. This name will occur again in an 
EXTDEF record. 

ModuleName in <count, char> string format and is the name of the module 
which supplies an export symbol matching this import. 

Entryldent is an ordinal or the name used by the exporting module for the 
symbol, depending upon the OrdFIag. 

If this field is an ordinal (OrdFIag nonzero), it is a 16-bit word. If this 
is a name, and the first byte of the name is zero, then the exported 
name is the same as the import name (in the InternalName field). 
Otherwise, it is the imported name in <count, char> string format 
(as exported by ModuleName ). 


Notes: 

IMPDEF records are created by the utility IMPLIB, which builds an “import 
library’’ from a module definition file or dynamic-link library. 
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88H EXPDEF Export Definition Record 
(comment class AO, subtype 02) 

Description: 

This record describes the exported names for a module. 

Record format: 

One exported entry point is described; the subrecord format is 


1 

1 

< variable > 

< variable > 

2 (bytes) 

02 

Exp 

Exported 

Internal 

Export 


Flag 

Name 

Name 

Ordinal 


<conditional> 


FIGURE 7.10 

EXPDEF record type definition, 
where: 

02 identifies the subtype as an EXPDEF 
ExpFlag is a bit-significant 8-bit field. 


<-1 byte-> 


Ord 

Resident 

No 

Farm 

Bit 

Name 

Data 

Count 


1 1 1 <-5 bits-> 


OrdBit Set if the item is exported by ordinal; in this case the ExportOrdinal 
field is present. 

ResName Set if the exported name is to be kept resident by the system 
loader; this is an optimization for frequently used items imported by 
name. 

NoData Set if the entry point does not use initialized data (either instanced 
or global). 

ParmCount Number of parameter words. The ParmCount field is set to 
zero for all but callgates to 16-bit segments. 
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Exported Name 

in ccount, char> string format. Name to be used when the entry point is 
imported by name. 

Internal Name 

in <count, char> string format. If the name length is zero, the internal 
name is the same as the Exported Name. Otherwise, it is the name by which 
the entry point known within this module. This name will appear as a PUBDEF 
or LPUBDEF name. 

ExportOrdinal 

present if the OrdBit is set; it is a 16-bit numeric whose value is the ordinal 
used (must be non-zero). 

Notes: 

EXPDEFs are produced by the compiler when the keyword export is used 
in a source file. LINK386 limits the ExportOrdinal value to 16384(16K) or 
lower. 
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88H INCDEF Incremental Compilation Record 
(comment class A6 9 subtype 03) 

Description: 

This record is used for incremental compilation. Every FIXUPP and 
LINNUM record following an INCDEF record will adjust all external index 
values and line number values by the appropriate delta. The deltas are cu¬ 
mulative if there is more than one INCDEF per module. 

Record format: 

The subrecord format is 


1 

2 

2 

<variable> (bytes) 

03 

EXTDEF 

delta 

LINNUM 

delta 

padding 


FIGURE 7.11 

INCDEF record type definition. 

The EXTDEF delta and LINNUM delta fields are signed. 

Padding (zeros) is added by Quick C to allow for expansion of the object 
module during incremental compilation and linking. 


Notes: 


Negative deltas are allowed. 
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88H LNKBIR C++ Directives Record 
(comment class AO, subtype 05) 

Description: 

This record is used by the compiler to pass directives and flags to the linker. 

Record format: 


The subrecord format is 



1 

1 

1 

1 (bytes) 


05 

Bit Flags 

Pseudocode Vers 

CV Vers 


FIGURE 7+2 

LNKDIR record type definition. 


The format of the Bit Flags byte is: 

8 111111 1 1 (bits) 


05 

0 

0 

0 

0 

0 

Run 

Omit CV 

New 







MPV 

Publics 

EXE 


FIGURE 7.13 

BIT FLAGS byte definition. 

The low-order bit, if set, indicates that LINK386 should output the new 
EXE format; this flag is ignored for all but linking of Pseudocode applica¬ 
tions. (Pseudocode requires a segmented executable). 

The second low-order bit indicates that LINKS86 should not output the 
SPUBL1CS subsection of the CodeView info. 

The third low-order bit indicates that MPC (Microsoft Make Pseudocode 
Utility) should be run. 

Pseudocode Version 

One byte indicating the Pseudocode interpreter version number. 
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CodeView Version 

One byte indicating the CodeView version number. 


Notes: 

The presence of this record in an object module will indicate the presence 
of global symbols records. The linker will not emit a Publics section for 
those modules with this comment record and a $S YMBOLS section. 
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88H LIBMOD Library Module Name Record 
(comment class A3) 

Description: 

The LIBMOD comment record is used only by the LIB utility, not by LINK. It 
gives the name of an object module within a library, allowing LIB to preserve 
the library file name in the THEADR record and still identify the module names 
that make up the library. Since the module names is the basename of the 
.OBJ file that was built into the library, it may be completely different from 
the final library name. 

Record format: 

The subrecord format is 


1 < variable > (bytes) 


A3 


Module Name 


FIGURE 7.14 

LIBMOD record type definition. 

The record contains only the ASCII string of the module name, in < count, 
char> format. The module name has no path and no extension, just the base 
of the module name. 

Notes: 

LIB adds a LIBMOD record when a .OBJ file is added to a library and strips 
the LIBMOD record when a .OBJ file is removed from a library, so typically 
this record only exists in .LIB files. 

There will be one LIBMOD record in the library file for each object module 
that was combined to build the library. 

LINK386 ignores LIBMOD coment records. 
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88H EXESTR Executable String Record 
(comment class A4) 

Description: 

The EXESTR comment record implements the ANSI and XENIX/UNIX 
features in C: 

• #pragma comment (exestr, <char-sequence>) 

• #ident string 

Record format: 

The subrecord format is 


1 < variable > (bytes) 


A4 


arbitrary text 


FIGURE 7.15 

EXESTR record type definition. 

The linker will copy the text in the “arbitrary text” field byte for byte to 
the end of the executable file. The text will not be included in the program 
load image. 

Notes: 

If CodeView information is present, the text will not be at the end of the file, 
but somewhere before so as not to interfere with the Code View signature. 
There is no limit to the number of EXESTR comment records. 
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88H INCERR Incremental Compilation Error 
(comment class A6) 

Description: 

This comment record will cause the linker to terminate with the fatal error 
saying something to the effect of “invalid object - error encountered during 
incremental compilation”. 

The purpose of this is for the case when an incremental compilation fails 
and the user tries to manually link, the object module cannot be deleted, in 
order to preserve the base for the next incremental compilation. 

Record format: 

The subrecord format is 


1 (bytes) 


A6 


No fields 


FIGURE 7.16 

INCERR record type definition. 
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88H NOPAD No Segment Padding 
(comment class A6) 

Description: 

This comment record identifies a set of segments which are to be excluded 
from the padding imposed with the /PADDATA or /PADCODE options. 

Record format: 

The subrecord format is 


1 1 or 2 (bytes) 


A 7 


SEGDEF Index 


FIGURE 7,17 

NOPAD record type definition. 

The SEGDEF Index is the standard OMF index type of 1 or 2 bytes. It may 
be repeated. 


Notes: 

LINK386 ignores NOPAD coment records. 
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88B WKEXT Weak Extern Record 
(comment class A8) 

Description: 

This record marks a set of external names as “weak”, and for every weak 
extern associates another external name to use as the default resolution. 


Record format: 

The subrecord format is 


1 or 2 


or 2 


(bytes) 


A8 


Weak EXTDEF Index 


Default resolution EXTDEF Index 


Repeated - 


FIGURE 7.18 

WEAK EXTERN record type definition. 

The Weak EXTDEF Index field is the 1 or 2 byte index to the EXTDEF of the 
extern which is weak. 

The Default Resolution EXTDEF Index is the 1 or 2 byte index to the 
EXTDEF of the extern that will be used to resolve the extern if no “stronger” 
link is found to resolve it. 

Notes: 

There are two ways to cancel the “weakness” of a weak extern; both result 
in the extern becoming a “strong” extern (the same as an EXTDEF). They are: 

• if a PUBDEF for the weak extern is linked in, 

• if an EXTDEF for the weak extern is found in another module (includ¬ 
ing libraries). 

If the weak extern becomes strong, then it must be resolved with a matching 
PUBDEF, just like a regular EXTDEF. If a weak extern has not become strong 
by the end of the linking process, then the default resolution is used. 

If two weak externs for the same symbol in different modules have differing 
default resolutions, LINKS86 will emit a warning. 
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Weak extems do not query libraries for resolution; if an extern is still 
weak when libraries are searched, it stays weak and gets the default reso¬ 
lution. However, if a librai'y module is linked in for other reasons (say, to 
resolve strong externs) and there are EXTDEFs for symbols that were weak, 
the symbols become strong. 

For example, suppose there is a weak extern for “foo” with a default 
resolution name of “bar”. If there is a PUBDEF for “foo” in some library 
module which would not otherwise be linked in, then the library module is 
not linked in, and any references to “foo” are resolved to “bar”. However, 
if the library module is linked in for other reasons, for example to resolve 
references to a strong extern named “bletch”, then “foo” will be resolved by 
the PUBDEF from the library, not to the default resolution “bar”. 

WKEXTs are best understood by explaining why they were added in the first 
place. The minimum BASIC runtime library in the past consisted of a large 
amount of code which was always linked in, even for the smallest program. 
Most of this code was never called directly by the user, but it was called 
indirectly from other routines in other libraries, so it had to be linked in to 
resolve the external references. 

For instance, the floating point library was linked in even if the user’s pro¬ 
gram did not use floating point, because the PRINT library routine contained 
calls to the floating point library for support to print floating point numbers. 

The solution was to make the function calls between the libraries into weak 
externals, with the default resolution set to a small stub routine. If the user 
never used a language construct or feature that needed the additional library 
support, then no strong extern would be generated by the compiler and the 
default resolution (to the stub routine) would be used. However, if the user 
accessed the library’s routines or used constructs that required the library’s 
support, a strong extern would be generated by the compiler to cancel the 
effect of the weak extern, and the library module would be linked in. This 
required that the compiler know a lot about which libraries are needed for 
which constructs, but the resulting executable was much smaller. 
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88H LZEXT Lazy Extern Record 
(comment class A9) 

Description: 

This record marks a set of external names as “lazy”, and for every lazy 
extern associates another external name to use as the default resolution. 


Record format: 

The subrecord format is 


1 or 2 


1 or 2 


(bytes) 


A8 


Lazy EXTDEF Index 


Default resolution EXTDEF Index 


-Repeated- 


FIGURE 7.19 

LAZY EXTERN record type definition. 

The Lazy EXTDEF Index field is the 1 or 2 byte index to the EXTDEF of the 
extern which is weak. 

The Default Resolution EXTDEF Index is the 1 or 2 byte index to the EXTDEF 
of the extern that will be used to resolve the extern if no “stronger” link is 
found to resolve it. 

Notes: 

There are two ways to cancel the “laziness” of a lazy extern; both result in 
the extern becoming a “strong” extern (the same as an EXTDEF). They are: 

• if a PUBDEF for the weak extern is linked in, 

• if an EXTDEF for the weak extern is found in another module (includ¬ 
ing libraries). 

If a lazy extern becomes strong, then it must be resolved with a matching 
PUBDEF, just like a regular EXTDEF. If a lazy extern has not become strong 
by the end of the linking process, then the default resolution is used. 

If two weak externs for the same symbol in different modules have differing 
default resolutions, LINK will emit a warning. 
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Unlike weak extems, lazy extems do not query libraries for resolution; if 
an extern is still lazy when libraries are searched, it stays lazy and gets the 
default resolution. 

LINK386 ignores LZEXT coment records. 
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88H IDMDLL Identifier Manipulator DLL 
(comment class AF) 

Description: 

This record provides the name and initialization parameters of a DLL that 
will demangle the compiler generated mangled names. The linker will use 
this DLL when displaying error messages. 


Record format: 

The Subrecord Format is: 


1 

1 

< —Name Length— > 

1 

< —Parms Length— > 

OxAF 

Name 

DLL Name 

Parms 

Demangle Init 


Length 


Length 

Parameters 


FIGURE 7.20 

IDMDLL Identifier Manipulator DLL subrecord format definition. 


The Name Length byte gives the number of characters in the DLL Name; 
the DLL Name itself is ASCII. 

The DLL Name is the name of the Identifier Manipulator Dynamic Link 
Library provided by the language. This DLL is used to demangle an internal 
identifier when that identifier will be displayed in an error message. 

The Parms Length byte gives the number of characters in the Depiangle 
Init Parameters; the Demangle Init Parameters itself is ASCII. 

The Demangle Init Parameters provides information (to the DLL) on how 
internal identifiers are mangled. 

The linker will not scan forward for an IDMDLL record when an identifier 
will be displayed. This record should occur near the beginning of the file. 

IDMDLL class COMENT records are processed during pass 1 of the linker. 


Notes: 

Because object oriented compilers allow for two functions to have the 
same name but different parameters, the compiler uniquely identifies each 
function by changing the name of the function. This is known as mangling. 
An example of this would be: 
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User Prototype Compiler Generated 

Mangled Name 

void doit( int, float) _doit_Fif 

void doit( const char *) _doit_FCPc 

The user will usually not be aware that the compiler changed the name, so 
it is necessary for the linker to demangle the compiler generated name when 
printing out linker error messages. 

The dynamic link library (DLL) provided by an object oriented language 
compiler must contain two 16-bit functions which employ the pascal calling 
convention: 

INITDEMAN GLEID 

Receive initialization parameters specified in the IDMDLL COM ENT record. 

DEMANGLEID 

Demangles first parameter (identifier, “_add _i_ii”) to appropriate 

prototype (i.e., “i nt add(i nt, i nt)”) and returns result in second param¬ 
eter. 

The INITDEMAN GLEID and DEMANGLEID entry points may be called 
more than once. 

All functions must return true (non-zero) if the call is successful and false 
(zero) if the call fails. In this manner the linker can ignore whatever is re¬ 
turned in the second parameter of the DEMANGLEID function if the func¬ 
tion returns false. When calling DEMANGLEID, the linker will pass in the 
address of a buffer for the second parameter, and the size of the buffer for 
the third parameter. 

All string parameters must be length-prefixed ASCII strings except for 
pszPrototype, parameter 2 for DEMANGLEID (because the length might 
not fit in a byte). Function prototypes for these routines look like: 

unsigned short pascal far INITDEMANGLEID(char far * 

pslnitParms); 

unsigned short pascal far DEMANGLEID( 

char far * psMangledName, 
char far * pszPrototype, 
unsigned long BufferLen); 

NOTE 

Languages may also wish to provide 32-bit functions for use by 32-bit 
linkers, when they become available. Function prototypes look like: 
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unsigned long _system InitDemangleID32(char * pslnitParms); 


unsigned long _system DemangleID32(char * psMangledName, 

char * pszPrototype, 
unsigned long BufferLen) 
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88H PharLap Format Record 
(comment class AA) 

Description: 

The OMF extension designed by PharLap is called “Easy OMF-386” and 
changes to the affected record types are described in this section. 

Most modifications involve only a substitution of 32-bit (4-byte) fields for 
what were formerly 16-bit (2-byte) fields. In the two cases where the changes 
involve more than just a field size (in the SEGDEF and FIXUPP records), the 
information is mentioned in this section but complete details are given in the 
sections describing the specific records. 


Record format: 

The subrecord format is 


AA 


“80366" 


Notes: 

The AA comment record should come immediately after the sole THE ADR 
record. Presence of the comment record indicates that the following other 
record types have fields that are expanded from 16-bit to 32-bit values: 


SEGDEF offset field and offset field length 
PUBDEF offset field 
LEDATA offset field 

LIDATA offset field (note that repeat count field is still 16 bits) 

FIXUPP target displacement in explicit FIXUP subrecord 

BLKDEF return address offset field 

LINNUM offset field 

MODEND target displacement field 
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FIXUPP records 

have the added Loc values of 5 and 6. See the FIXUPP section of this 
document for details. 

SEGDEF records 

have added alignment values (for 4-byte alignment and 4K byte alignment) 
and an added optional byte at the end which contains the Use 16/Use32 bit flag 
and access attributes (read/write/execute) for the segment. See the SEGDEF 
section of this document for details. 

LINK386 ignores PHARLAP coment records. 
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BAH or 8BH MODEND Module End Record 

Description: 

The MODEND record denotes the end of the object module. It also indicates 
whether the object module contains a main routine in a program, and it can, 
optionally, contain a reference to a programs entry point. 

Record format: 


1 byte 


2 bytes 



1 byte 

1 byte 

1 or 2 

1 or 2 

2 or 4 bytes 

1 byte 

Module 

Type 

End 

Data 

Frame 

Datum 

Index 

Target 

Datum 

Index 

Target 

Displacement 

Chk Sum 
OrO 


— Start Address, conditional 


—> 


FIGURE 7.21 

MODEND module end record, 
where: 

Module Type 

The module type byte is bit-significant; layout is: 


MATTR Main Strt 

Seg Bit 


0 


0 

x 

2 bits 

1 

i 

1 

1 

1 

1 


where: 


MATTR is a 2-bit field 


Main is set if the module is a main module 
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Strt is set if the module contains a start address; if this bit is set, 
the field starting with the EndDat byte is present and specifies 
the start address. 

SegBit Reserved. Only 0 is supported by OS/2. 

X This bit should be set (as described for OMF86). However, as is 
the case for the OMF86 linkers, the value will be ignored. 

Start Address 

The Start Address subfield is present only if the Strt bit in the Module 
Type byte is set. Its format is identical to the FixDat, Frame Datum, Target 
Datum, and Target displacement in a FIXUP subrecord of a FIXUPP record. 
The displacement (if present) is a 4 byte field if the record type is 8BH and is a 
2-byte field if the record type is 8AH. This value provides the initial contents 
of CS:(E)IP. 

The start address must be given in the MODEND record of the root module 
if overlays are used. 

Notes: 

A MODEND record can appear only as the last record in an object module. 
It is assumed that the link pass separator comment record (COMENT A2, 
subtype 01) will not be present in a module whose MODEND record contains 
a program starting address. 
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8CH EXTDEF External Names Definition Record 
Description: 

The EXTDEF record contains a list of symbolic external references— that is, 
references to symbols defined in other object modules. The linker resolves 
external references by matching the symbols declared in EXTDEF records 
with symbols declared in PUBDEF records. 

Record format: 


1 byte 2 bytes 


8C 


Record Length 


1 byte 

< string > 

1 or 2 

1 byte 

String 

External 

Type 

Chk Sum 

Length 

Name String 

Index 

or 0 

<- 

— repeated — 

-> 



FIGURE 7.22 

EXTDEF external names definition record. 

This record provides a list of unresolved references, identified by name and 
with optional associated type information. The external names are ordered 
by occurrence jointly with the COMDEF and LEXTDEF records and referenced 
by an index in other records (FIXUPPs); the name may not be null. Indices 
start from one. 

String Length is a 1-byte field containing the length of the name field that 
follows it. The length of the name is restricted to 255 bytes. 

The Type Index is encoded as an index field and contains debug informa¬ 
tion. No type checking is performed by the linker. 

Notes: 

The linker imposes a limit of 1023 external names. 

Any EXTDEF records in an object module must appear before the FIXUPP 
records that reference them. 
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Resolution of an external reference is by name match, (case sensitive) and 
symbol type match. The search first looks for a matching name, in the 
sequence: 

1. Searches PUBDEF and COMDEF for resolution. 

2. If linking a segmented executable, searches imported names (IMPDEF). 

3. If this is not a DLL, then searches for an export (EXPDEF) with the 
same name—a self-imported alias. 

4. Searches for the symbol name among undefined symbols. If the 
reference is to a weak extern, then the default resolution is used. If 
the reference is to a strong extern, then it’s an undefined external and 
a link error is generated. 

All external references must be resolved at link time (using the above 
search order). Even though the linker produces an executable file for and 
unsuccessful link session, an error bit is set in the header which prevents the 
loader from running the executable. 
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90H or 91H PUBDEF Public Names Definition Record 
Description: 

The PUBDEF record contains a list of public names. It makes items defined 
in this object module available to satisfy external references in other modules 
with which it is bound or linked. 

The symbols are also available for export if so indicated in an EXPDEF 
comment record. 

Record format: 


2 bytes 



1 or 2 

1 or 2 

2 bytes 

1 byte 

< string > 

2 or 4 bytes 

1 or 2 

1 byte 

Base 

Group 

Index 

Base 

Segm. 

Index 

Base 

Frame 

Str. 

Len 

Public 

Name 

str. 

Public 

Offset 

Type 

Index 

Chk 

sum 

or 0 



<cndl> 

< 

-repeated- 

> 



FIGURE 7.23 

PUBDEF Public Names Definition Record. 


Base Group, Base Segment and Base Frame 

The base group and segment are indices specifying previously defined 
SEGDEF and GRPDEF records. The group index may be zero, meaning that no 
group is associated with this PUBDEF record. 

The Base Frame field is present only if the Base Segment is zero, but the 
content of the Base Frame is always ignored by the linker. 

The Segment Index is normally nonzero and no Base Frame is present. 

The Base Frame is normally used for absolute addressing when the Group 
and Segment Index are both zero. Absolute addressing is not fully supported 
in the linker. 
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Public name, Public Offset and Type Index 

The public name string is in <count, char> form and cannot be null. The 
maximum length of a public name is 255 bytes. 

The public offset is a 2 or 4 byte numeric field containing the offset of the 
location referred to by the public name. This offset is assumed to lie within 
the segment, group or frame specified in the public base field. 

The Type Index field is encoded in index format; it contains either debug 
type information or zero. This field is ignored by the OS/2 2.0 linker. 

NOTES: 

All defined functions and initialized global variables generate PUBDEF 
records. 

Any PUBDEF records in an object module must appear after the GRPDEF 
and SEGDEF records to which they refer. 

The IBM C Compiler will generate PUBDEF records for all defined func¬ 
tions and initialized global variables. Globals for scalars that are initialized 
to zero produce COMDEF records. 

Record type 90H uses 16-bit encoding of the Public Offset, but it is zero- 
extended to 32 bits if applied to Use32 segments. 



APPENDIX 


143 


94H or 95H LINNUM Line Number Record 

Description: 

The LINNUM record relates line number within language source state¬ 
ments to addresses in the object code. 

Record format: 


1 byte 

2 bytes 

94 or 

Record Length 

95 



1 or 2 1 or 2 1 byte 


Base 

Base 

Debugger Style 

Chk sum 

Group 

Segment 

Specific 

orO 

Index 

Index 

Information 



<- repeated -> 


FIGURE 7,24 

LINNUM line number record. 

Associates a source line number with translated code or data. The LINNUM 
record is only generated when the debug option is selected and is therefore 
specific to the debug information. Refer to the specific debug documentation 
for more information. 

Base Group and Base Segment 

The Base group and Base segment are indices specifying previously de¬ 
fined GRPDIEF and SEGDEF records. The group index is ignored. The segment 
index must be nonzero unless the debugger style is version 3 or greater of 
the IBM PM debugger format. 
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96H LNAMES List of Names Record 
Description: 

The LNAMES record is a list of names that can be referenced by subsequent 
SEGDEF and GRPDEF records in the object module. 

The names are ordered by occurrence and referenced by index from sub¬ 
sequent records. More than one LNAMES record may appear. The names 
themselves are used as segment, class and group names. 


1 byte 2 bytes 


96 


Record Length 


< String Length > 1 byte 


String 

Name 

Chk Sum 

Length 

String 

or 0 


<— repeated —> 


FIGURE 7.25 

LNAMES list of names record. 

Each name appears in count/char format, and a null name is valid. The 
character set is ASCII. 

NOTES: 

The linker imposes a limit of 255 logical names per object module. 

Any LNAMES records in an object module must appear before the records 
that refer to them. Because it does not refer to any other type of object record, 
an LNAMES record usually appears near the start of an object module. 
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98H or 99H SEGDEF Segment Definition Record 
Description: 

The SEGDEF record describes a logical segment in an object module. It 
defines the segment’s name, length and alignment, as well as the way the 
segment can be combined with other logical segments at bind, link and load 
time. 

Object records that follow the SEGDEF record can refer to it to identify a 
particular segment. The SEGDEF records are ordered by occurrence and are 
referenced by segment indexes (origin 1) in subsequent records. 

Record format: 


1 byte 2 bytes 


98 or 
99 


Record Length 


< variable > 

2 or 4 bytes 

1 or 2 

1 or 2 

1 or 2 

1 byte 

Segment 

Segment 

Segment 

Class 

Overlay 

Chk Sum 

Attribute 

Length 

Name 

Name 

Name 

or 0 



Index 

Index 

Index 



FIGURE 7.26 

SEGDEF segment definition record. 


Segment Attributes 

The segment attribute is bit-significant; the layout is: 


< 3 bits > 

< 3bits > 

< lbit > 

< — 1 bit — > 

2 bytes 

1 byte 

1 A 

C 

B 

P 

Frame Number 

Offset 





<cond> 

<cond> 


The fields have the following meaning: 
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A alignment, a 3-bit field, which specifies the alignment required when this 
program segment is placed within a logical segment. Values are: 

0 absolute segment 

1 relocatable, byte aligned 

2 relocatable, word (2 byte, 16-bit) aligned 

3 relocatable, paragraph (16 byte) aligned 

4 relocatable, aligned on page (4K byte) boundary. 

5 relocatable, aligned on double word (4 byte) boundary 

6 not supported 

7 not defined 

The new values are A=4 and A=5. Dword alignment is expected 
to be useful as 32-bit memory paths become more prevalent. 
Page-align maps to the 80386 hardware page size of 4K bytes. 

C combination, a 3-bit field, which determines the way the program seg¬ 
ment is mapped into a logical segment. Values are: 

0 private, do not combine with any other program segment 

1 reserved 

2 public, combine by appending at an offset which meets the 
alignment requirement 

3 reserved 

4 same as C=2 (public) 

5 stack, combine as for C=2. 

6 common, combine by overlay using maximum size 

7 same as C=2 (public) 

B big, used as the high order bit of the segment length field. If this bit is 
set the segment length value must be zero and the segment’s size is 
2<?32 or 4Gbytes long. 

P Holds the descriptor table B/D bit value (this is the descriptor table D bit 
for code segments and the B bit for data segments). 

If zero, then segment is no larger than 64K (if data) and 16-bit ad¬ 
dressing and operands are the default (if code). This is a Use 16 
segment. 

If not zero, then the segment is no larger than 64k (if data) and 32-bit 
addressing and operands are the default (if code). This is a Use32 
segment. 

Note that this is the only method for defining Use32 segments. 
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Segment Length 

The Segment Length is a 2 or 4 byte numeric quantity and specifies the 
number of bytes in this program segment. 


NOTE 

For record type 9 8 H, the length can be from 0 to 64K; if a segment is exactly 
64KB in size, segment length should be 0 and the B field in the ACPB byte 
should be 1. For record type 99H, the length can be from 0 to 4G; If segment 
is exactly 4Gbytes in size, segment length should be set to zero and the B 
field in the ACBP byte should be set to 1. 

Segment Name Index, Class Name Index, Overlay Name Index 

The three name indices refer to names that appeared in previous LNAMES 
record(s). The linker ignores the overlay name index. The full name of 
a segment consists of the segment and class names. Segments in different 
object modules are normally combined according to the A and C values if 
their full names are identical. These indices must be nonzero, although the 
name itself may be null. 

The segment name index identifies the segment with a name, the name 
need not be unique—other segments of the same name will be concatenated 
onto the first segment with that name. The name may have been assigned by 
the programmer, or it may have been generated by the compiler. 

The class name index identifies the segment with a class name (such as 
CODE, DATA or STACK). The linker places segments with the same class 
name into a contiguous area of memory in the run-time memory map. 

The overlay index is ignored by the linker. 

Notes: 

The linker imposes a limit of 255 SEGDEF records per object module. 

The following name/class combinations are reserved: 

S$TYPE Preserved for Debug types. 

$$SYMBOLS Reserved for Debug names. 

CODE32 Reserved for IBM C Compiler. 

DATA32 Reserved for IBM C Compiler. 

C0NST32 Reserved for IBM C Compiler. 

BSS32 Reserved for IBM C Compiler. 

DGROUP32 Reserved for IBM C Compiler. 
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9AH GRPDEF Group Definition Record 
Description: 

The GRPDEF record causes the program segments defined by SEGDEF 
records to be collected together (grouped). For OS/2 2.0, the segments are 
combined into a logical segment which is to be addressed through a single 
selector for flat memory. 

Record format: 


1 byte 

2 bytes 

1 or 2 

1 

1 or 2 

1 (bytes) 

9A 

Record 

Length 

Group 
Name Index 

FF 

Segment 
Def. Index 

Chk Sum 
orO 


<- repeated -> 


FIGURE 7.27 

GRPDEF group definition record. 


This record causes the program segments identified by SEGDEF records 
to be collected together (grouped) within a logical segment which is to be 
addressed through a single selector. 

Group Name 

The group name is specified as an index into a previously defined LNAMES 
name and must be nonzero. 

Groups from different object modules are coalesced if their names are 
identical. 

Group Components 

The group’s components are segments, specified as indices into previously 
defined SEGDEF records. 

The first byte of each group component is a type field for the remainder of 
the component. The linker requires a type value of FFH and always assumes 
that the component contains a segment index value. 

The component fields are usually repeated so that all segments constituting 
a group can be included in one GRPDEF record. 
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Notes: 

This record is frequently followed by a THREAD fixup. 

The linker imposes a limit of 31 GRPDEF records in a single object module 
and limits the total number of group definitions across all object modules to 
31 . 

An example of a group for the IBM C Compiler is DGROUP32 which 
groups DATA32, CONST32 and BSS32. 

The linker does special handling of the pseudo-group : FLAT. All address 
references to this group are made as offsets from the virtual zero address, 
which is the start of the memory image of the executable. 
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9CH or 9DH FIXUPP Fixup Record 
Description: 

The FIXUPP record contains information that allows the linker to resolve 
(fix up) and eventually relocate references between object modules. FIXUPP 
records describe the LOCATION of each address value to be fixed up, the 
TARGET address to which the fixup refers and the FRAME relative to which 
the address computation is performed. 

Record format: 


1 byte 

2 bytes 

<-from the record length-> 

1 byte 

9C 


THREAD subrecord 

Chk Sum 

or 

Record Length 

or 

or 0 

9D 


FIXUP subrecord 



< Repeated > 


FIGURE 7.28 
FIXUPP Fixup Record. 


Record type 9DH is new for LINK386; it has a Target Displacement field 
of 32 bits rather than 16 bits, and the LOC field of the LOG AT word has 
been extended to $ bits (using the previously unused higher-order ’S’ bit) to 
allow new LOC values of 9, 11 and 13. 

Each subrecord in a FIXUPP object record either defines a thread for sub¬ 
sequent use, or refers to a data location in the nearest previous LEDATA or 
LI DATA record. The high order bit of the subrecord determines the sub¬ 
record type: if the high order bit is 0, the subrecord is a THREAD subrecord; 
if the high order bit is 1, the subrecord is a FIXUP subrecord. Subrecords of 
different types may be mixed within one object record. 

Information that determines how to resolve a reference can be specified 
explicitly in a FIXUP subrecord, or can be specified within a FIXUP sub¬ 
record by a reference to a previous THREAD subrecord. A THREAD subrecord 
describes only the method to be used by the linker to refer to a particular 
target or frame. Because the same THREAD can be referenced in several sub¬ 
sequent FIXUP subrecords, a FIXUPP object record that uses THREADS may 
be smaller than one in which THREADS are not used. 

THREAD subrecords can be referenced in the same object record in which 
they appear and also in subsequent FIXUPP object records. 
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THREAD 

There are 4 frame threads and 4 target threads; not all need be defined and 
they can be redefined by later THREAD subrecords in the same or later FIXUPP 
object records. The frame threads are used to specify the Frame Datum field 
in a later FIXUP subrecord: the target threads are used to specify the Target 
Datum field in a later FIXUP subrecord. 

A THREAD subrecord defines a thread, and does not require that a previous 
LEDATA or LI DATA record occur. 

The layout of the THREAD subrecord is as follows: 



<- 


- one byte — 

-> 

1 or 2 bytes 

E 

D 

0 

METHOD 

THRED 

Index 

i 

1 

1 

3bits 

2 bits 

<- conditional -> 


where: 

0 The high order bit is zero to indicate that this is a THREAD subrecord. 

D is 0 for a target thread, 1 for a frame thread 
METHOD is a 3-bit field. 

For target threads , only the lower two bits of the field are used; 
the high-order bit of the method is derived from the P bit in the 
FixDat field of the FIXUP subrecords that refer to this thread. 
The full list of methods is given here for completeness. This 
field determines the kind of index required to specify the Target 
Datum. 

TO specified by a SEGDEF index 
T1 specified by a GRPDEF index 
T2 specified by a EXTDEF index 

T3 specified by an explicit frame number (not supported by the 
linker) 

T4 specified by a SEGDEF index only; the displacement in the 
FIXUP subrecord is assumed to be 0. 

T5 specified by a GRPDEF index only; the displacement in the 
FIXUP subrecord is assumed to be 0. 

T6 specified by a EXTDEF index only; the displacement in the 
FIXUP subrecord is assumed to be 0. 

The index type specified by the target thread method is encoded 
in the index field. 

For frame threads , the method field determines the Frame Datum 
field of subsequent FIXUP subrecords that refer to this thread. 
Values for the method field are: 
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FO the FRAME is specified by a SEGDEF index 
FI the FRAME is specified by a GRPDEF index 
F2 the FRAME is specified by a EXTDEF index. The linker 
determines the FRAME from the external name’s corre¬ 
sponding PUBDEF record in another object module, which 
specifies either a logical segment or a group. 

F3 invalid (The FRAME is identified by an explicit frame 
number; this is not supported by the linker) 

F4 the FRAME is determined by the segment index of the 
previous LEDATA or LIDATA record (i.e., the segment in 
which the location is defined). 

F5 the FRAME is determined by the TARGET’S segment, 
group or external index 
F6 invalid 

The index field is present for frame methods FO, FI, and 
F2 only. 

THREB is a 2-bit field and determines the thread number (0 through 3, for 
the 4 threads of each kind). 

Index is a conditional field that contains an index value that refers to a 
previous SEGDEF, GRPDEF or EXTDEF record. The field is only present 
if the thread method is 0, 1 or 2. If method 3 were supported by the 
linker, the Index field would contain an explicit frame number. 


FIXUP 

A FIXUP subrecord gives the how/what/why/where/who information re¬ 
quired to convert a reference when program segments are combined or placed 
within logical segments. It applies to the nearest previous LEDATA or LIDATA 
record, which must be defined before the FIXUP. This FIXUP subrecord is as 
follows: 


2 byte 1 byte 


1 or 2 


1 or 2 


2 or 4 bytes 


LOCAT Fix Dat Frame Datum | Target Datum I Target Displacement 


<cond> 


<cond> 


<conditional> 


where the LOCAT field has an unusual format. Contrary to the usual byte 
order in Intel data structures, the most significant bits of the LOCAT field are 
found in the low-order, rather than the high-order byte. 
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The LOCAT field is: 


<-10 byte-> <-high byte-> 


1 I M I LOCTData Record Offset 


1 1 


10 (bits) 


where: 

1 the high bit of the low-order byte is set to indicate a FIXUP subrecord. 

M is the mode, M=1 for segment-relative and M=0 for self-relative fixups 

LOC is a 4-bit field which determines what type of location is to be fixed 
up: 

0 Low-order byte (8-bit displacement or low byte of 16-bit off¬ 
set) 

1 16-bit Offset 

2 16-bit Base - logical segment base (selector) 

3 32-bit Long pointer (16-bit base: 16-bit offset) 

4 Hi-order byte (high byte of 16-bit offset) No linker support 
for this type. 

5 16-bit loader-resolved offset, treated as LOC=l by the linker 
CONFLICT PharLap OMF uses LOC=5 to indicate a 32-bit 
offset, where Microsoft and IBM use LOC=9. 

6 not defined, reserved 

CONFLICT PharLap OMF uses LOC=6 to indicate a 48-bit 
pointer (16-bit base: 32-bit offset) where Microsoft and IBM 
use LOC=ll. 

7 not defined, reserved 
9 32-bit offset 

11 48-bit pointer (16-bit base: 32-bit offset) 

13 32-bit loader-resolved offset, treated as LOC=9 by the linker 

Data Record Offset The Data record offset indicates the position of the 
location to be fixed up in the LEDATA or LIDATA record immediately 
preceding the FIXUPP record. This offset indicates either a byte in 
the data field of an LEDATA record or a data byte in the content field 
of an iterated data block in an LIDATA record. 
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The FixDat bit layout is: 


E 

FRAME 

E 

E 

TARGT 

1 

3 

1 

1 

2 (bits) 


and is interpreted as follows: 

F If F=l, the frame is given by a frame thread whose number is in the 
FRAME field (modulo 4). There is no frame datum field in the 
subrecord. 

If F=0, the frame method (in the range FO to F5) is explicitly defined 
in this FIXUP subrecord. The method is stored in the FRAME field. 

FRAME 3-bit numeric, interpreted according to the F bit. The Frame 
Datum field is present and is an index field for frame methods FO, 
FI, and F2 only. 

T If T=1 the target is defined by a target thread whose thread number is 
given in the 2-bit TARGT field. The TARGT field contains a number 
between 0 and 3 that refers to a previous thread field containing the 
target method. The P bit, combined with the two low-order bits of the 
method field in the THREAD subrecord, determines the target method. 
If T=0 the target is specified explicitly in this FIXUP subrecord. In 
this case, the P bit and the TARGT field can be considered a 3-bit 
field analogous to the FRAME field. 

P Determines whether the target displacement field is present. 

If P=1 there is no displacement field. 

If P=0, the displacement field is present. 

TARGT is a 2-bit numeric, which gives the lower two bits of the target 
method (if T=0) or gives the target thread number (if T=l). 

Frame Datum is an index field that refers to a previous SEGDEF, GRPDEF or 
EXTDEF record, depending on the FRAME method. 

Target Datum contains a segment index, a group index or an external index 
depending on the TARGET method. 

Target Displacement a 16-bit or 32-bit field is present only if the P bit in 
the FixDat field is set to 0, in which case the Target Displacement 
field contains the offset used in methods 0, 1 and 2 of specifying a 
TARGET. 
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Notes: 

FIXUPP records are used to fix references in the immediately preceding 
LEDATA, LIDATA or COMDAT record. 

The FRAME is the translator’s way of telling the linker the contents of 
the segment register used for the reference; the TARGET is the item being 
referenced whose address was not completely resolved by the translator. In 
protect mode, the only legal segment register value are selectors; every seg¬ 
ment and group of segments is mapped through some selector and addressed 
by offset within the underlying memory defined by that selector. 
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AOH or A1H LEDATA Logica! Enumerated Data Record 
Description: 

This record provides contiguous binary data—executable code or program 
data—which is part of a program segment. The data is eventually copied 
into the program’s executable binary image by the linker. 

The data bytes may be subject to relocation or fix-up as determined by the 
presence of a subsequent FIXUPP record but otherwise requires no expansion 
when mapped to memory at run time. 

Record Format: 


1 byte 2 bytes 


AO or 
A1 


Record Length 


1 or 2 

2 or 4 bytes 

<from Record Length > 

1 byte 

Seg. 

Enum Data 

Data 

Chk Sum 

Index 

Offset 

Bytes 

or 0 


FIGURE 7.29 

LEDATA logical enumerated data record. 

Record type A1H is new for LINKS86; it has an Enumerated Data Offset field 
of 32 bits rather than 16 bits. 

Segment Index 

The Seglndex must be nonzero and is the index of a previously defined 
SEGDEF record. This is the segment into which the data in this LEDATA record 
is to be placed. 

Enumerated Data Offset 

The enumerated data offset is a 2 or 4 byte field (depending on the record 
type) which determines the offset at which the first data byte is to be placed 
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relative to the start of the SEGDEF segment. Successive data bytes occupy 
successively higher locations. 

Data Bytes 

The maximum number of data bytes is 1024, so that a FIXUPP location 
field, which is 10 bits, can reference any of these data bytes. The number 
of data bytes is computed as the RecLength minus 5 minus the size of the 
Seglndex field (1 or 2 bytes). 

NOTES: 

Record type A1H has offset stored as a 32-bit numeric. Record type AO 
encodes the offset value as a 16-bit numeric (zero extended if applied to a 
Use32 segment). 

If the LEDATA requires fixup, a FIXUPP record must immediately follow 
the LEDATA record. 
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A2H or A3H LIDATA Logical Iterated Data Record 
Description: 

Like the LEDATArecord, the LI DATA record contains binary data—executable 
code or program data. The data in an LIDATA record, however, is specified 
as a repeating pattern (iterated), rather than by explicit enumeration. 

The data in an LIDATA record may be modified by the linker if the LIDATA 
record is immediately followed by a FIXUPP record. 

Record format: 


1 byte 2 bytes 


A2 or 
A3 


Record Length 


1 or2 

4 bytes 

<- from Record Length -> 

1 byte 

Seg. 

Data 

Data 

Chk sum 

Index 

Offset 

Block 

or 0 


<-repeat-> 


FIGURE 7.30 

LIDATA logical iterated data record. 

Record type A3H is new for LINK386; it has Iterated Data Offset and 
Repeat Count fields of 32 bits rather than 16 bits. 

Segment Index and Data Offset 

The segment index and data offset (2 or 4 bytes) are the same as for an 
LEDATA record. The index must be nonzero. 
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Data Block 

The data blocks have the following form: 


2 or 4 


< from block count > (bytes) 


Repeat Count | Block Count 


Content 


Repeat Count 

The Repeat Count is a 16-bit or 32-bit value which determines the number 
of repeats of the content field. The Repeat Count is 32 bits only if the record 
type is A3. 

CONFLICT: The PharLap OMF uses a 16-bit repeat count even in 32-bit 
records. 

Block Count 

The Block Count is a 16-bit word whose value determines the interpretation 
of the content portion, as follows: 

0 indicates that the content field that follows is a one byte “count” value 
followed by “count” data bytes. The data bytes will be mapped to 
memory, repeated Repeat Count times. 

!=0 indicates the content field that follows is comprised of one or more 
Data Blocks. The Block Count value specifies the number of Data 
Blocks (recursive definition). 


Notes: 

A subsequent FIXUPP record may occur; the fixup is applied before the 
iterated data block is expanded. It is a translator error for a fixup to reference 
any of the count fields. 
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BOH COMDEF Communal Names Definition Record 

Description: 

The COMDEF record declares a list of one or more communal variables 
(uninitialized static data, or data that may match initialized static data in 
another compilation group). 

The size of such a variable the maximum size defined in any module 
naming the variable as communal or public. The placement of communal 
variables is determined by the data type using established conventions (see 
data type and communal length below). 

Record format: 


2 bytes 



1 byte 

< string > 

1 or 2 

1 byte 

< from data type > 

1 byte 

Str. 

Len 

Communal 

Name 

Type 

Index 

Data 

Type 

Communal 

Length 

Chk sum 
or 0 


<- 

— repeated- 

-> 



FIGURE 7.31 

COMDEF communal names definition record. 


Communal name 

The name is in <count, char> string format (and name may be null). Near 
and Far communals from different object files are matched at bind or link 
time if their names agree; the variable’s size is the maximum of the sizes 
specified (subject to some constraints, as documented below). 

Type Index 

Encodes symbol information; it is parsed as an index field (one or 2 bytes), 
and not inspected by the linker. 
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Data Type and Communal Length 

The data type field indicates the contents of the Communal Length field. 
All Data type values for Near data indicate that the Communal Length field 
has only one numeric value: the amount of memory to be allocated for 
the communal variable. All Data Type values for Far data indicate that the 
Communal Length field has two numeric values: the first is the number of 
elements and the second is the element size. 

The DataType is one of the following hex values: 

61H 

FAR data; length specified as number of elements followed by element 
size in bytes. 

62H 

NEAR data; length specified as number of bytes. 

The communal length is a single numeric or a pair of numeric fields (as 
specified by the Data Type), encoded as follows: 

1 byte value 0 through 128 (80 hex) 

3 byte byte 81 hex, followed by a 16-bit word whose value is used 
(range 0 to 64K-1) 

4 byte byte 84 hex, followed by a 3 byte value (range 0 to 16M-1) 

5 byte byte 88 hex, followed by a 4 byte value (range -2G-1 to 2G-1, 
signed) 

Groups of name, type index, segment type and communal length fields 
can be repeated so that more than one communal variable can be declared in 
the same COMDEF record. 

Notes: 

If a public or exported symbol with the same name is found in another 
module with which this is bound or linked, the linker gives a multiple defined 
symbol error message. 

Communal variables cannot be resolved to dynamic links (i.e., imported 
symbols). 

The records are ordered by occurrence, together with the items named in 
EXTDEF records (for reference in FIXUPS). 

The IBM C Compiler generates COMDEF’s for all uninitialized global 
data and for global scalars initialized to zero. 
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B2H or B3H BAKPAT Backpatch Record 
Description: 

This record is for backpatches to locations which cannot be conveniently 
handled by a FIXUPP at reference time. For example, forward references in 
a one-pass compiler. It is essentially a specialized fixup. 

Record format: 


1 or 2 


2 or 4 2 or 4 1 (bytes) 


B2 or B3 J Record Length | Seg Index | Loc Type | Offset | Value | Chk Sum | 


<- repeated -> 


FIGURE 7.32 

BAKPAT Backpatch record 


Seglndex Segment index to which all “backpatch” fixupps are to be applied. 
Note that, in contrast to FIXUPs, these records need not follow the 
data record to be fixed up. Hence, the segment to which the backpatch 
applies must be specified explicitly. 

LocTyp Type of location to be patched; the only valid values are: 

0 8-bit lobyte 

1 16-bit offset 

9 32-bit offset, record type B3 only 

Offset and value These fields are 32-bits for record type B3, 16-bit for B2. 
The Offset specifies the location to be patched (as an offset into the 
segdef whose index is Seglndex). 

The associated Value is added to the location being patched (unsigned 
addition, ignoring overflow). The Value field is fixed length (16- 
bit or 32-bit, depending on the record type) to make object module 
processing easier. 


Notes: 

BAKPAT records can occur anywhere in the object module following the 
SEGDEF record to which they refer. They do not have to immediately follow 
the appropriate LEDATA record as FIXUPP records do. 
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These records are buffered by the linker in Pass 2 until the end of the 
module, after applying all other FIXUPPs. The linker then processes the 
records as fixups. 
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B4H or B5H LEXTDEF Local External Names Definition 
Record 

Description: 

This record is identical in form to the EXTDEF record described earlier. 
However, the symbols named in this record are not visible outside the module 
in which they are defined. 

Record format: 


1 

2 

1 

<- StrLen -> 

1 or 2 

1 (bytes) 

B4 or 

Record 

Str 

External 

Type 

Chk 

B5 

Length 

Len 

name string 

Index 

Sum 


<_repeated _> 


FIGURE 7.33 

LEXTDEF local external names definition record. 

Notes: 

There is no semantic difference between the B4 and B5 flavors. 

These records are associated with LPUBDEF and LCOMDEF records, ordered 
with the EXTDEF records by occurrence, so that they may be referenced by 
external index for fixups. 

The name string, when stored in LINK’S internal data structures, is encoded 
with spaces and digits at the beginning of the name. 
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B6H or B7H LPUBDEF Local Public Names Definition Record 
Description: 

This record is identical in form to the PUBDEF record described earlier. 
However, the symbols named in this record are not visible outside the module 
in which they are defined. 

Record format: 


1 

2 

1 or 2 

1 or 2 

2 

1 

<- strlen -> 

2 or 4 

1 or 2 

1 

B6 or 

Record 

Base 

Base 

Base 

Str 

Local 

Local 

Type 

Chk 

B7 

Length 

Grp 

Seg 

Frame 

Len 

Offset 

Offset 

Index 

Sum 


< end > <-repeated-> 


FIGURE 7.34 

LPUBDEF local public names definition record. 
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B8H LCOMDEF Local Communal Names Definition Record 
Description: 

This record is identical in form to the COMDEF record described earlier. 
However, the symbols named in this record are not visible outside the module 
in which they are defined. 

Record format: 


1 

2 

1 

<- strlen -> 

1 or 2 

1 

<— from data type —> 

1 

B8 

Record 

Str 

Communal 

Type 

Data 

Communal 

Chk 


Length 

Len 

Name 

Index 

Type 

Length 

Sum 


<-repeated-> 


FIGURE 7.35 

LCOMDEF local communal names definition record. 
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C2H or C3H COMDAT Initialized Communal Data Record 
Description: 

The purpose of the COMDAT record is to combine logical blocks of code 
and data which may be duplicated across a number of compiled modules. 


Record format: 


1 2 


C2 or 

Record Length 

C3 



1 1 1 2 or 4 1 or 2 < cond > <string>_1 1 


Flags 

Attr. 

Align 

Enum 

Type 

Public 

Public 

DAT 

Chk. 


Data 

Index 

Base 

Sum 






Offset 


Name 





<repeat> 


FIGURE 7.36 

COMDAT initialized communal data record. 


Flags 

This field contains three defined bits: 

01H - Continuation bit. If clear, then this COMDAT record establishes a new 
instance of the COMDAT variable, otherwise the data is a continuation of the 
previous COMDAT of the symbol. 

02H - Iterated data bit. If clear, the Dat field contains enumerated data, 
otherwise the Dat field contains iterated data, as in an LIDATA record. 

04H - Local COMDAT. The public name is local. 

Attr 

This field contains two 4-bit fields: the selection criteria to be used, the 
allocation type and the ordinal specifying the type of allocation to be per¬ 
formed. Values are: 

Selection criteria (high-order 4 bits): 
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OOH - No match - only one instance of this comdat allowed. 

I OH - Pick any - pick any instance of this COMDAT record. 

20H - Same size - pick any, but instances must have the same length or linker 
will generate an error. 

30H - Exact Match - pick any, but checksums of instances must match or 
linker will generate an error. Fixups are ignored. 

40H - FOH - reserved. 

Allocation T^pe (low-order 4 bits): 

OOH - Explicit - allocate in the segment specified in the ensuing public base 
field. 

01H - Far Code - allocate as CODE 16. The linker will create segments to 
contain all COMDAT’s of this type. 

02H - Far DATA - allocate as DATA 16. The linker will create segments to 
contain all COMDAT’s of this type. 

03H - CODE32 - allocate as CODE32. The linker will create segments to 
contain all COMDAT’s of this type. 

04H - DATA32 - allocate as DATA32. The linker will create segments to 
contain all COMDAT’s of this type. 

05H - OFH - Reserved. 

Align 

These codes are based on the ones used by the SEGDEF record: 

0 - use value from SEGDEF. 

1 - byte aligned. 

2 - word (2 byte) aligned. 

3 - paragraph (16 byte) aligned. 

4 - 4K page aligned. 

5 - dword (4 byte) aligned. 

6 - not defined. 

7 - not defined. 

Enum Data Offset 

This field specifies an offset relative to the beginning location of the symbol 
specified in the public name field and defines the relative location of the first 
byte of the DAT field. Successive data bytes in the DAT field occupy higher 
locations of memory. This works very much like the offset field in an LEDATA 
record, but instead of an offset relative to a segment, this is relative to the 
beginning of the COMDAT symbol. 
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Type Index 

The type index field is encoded in index format; it contains either debug 
type information or an old-style TYPDEF index. If this index is zero, there is 
no associated type data. Old-style TYPDEF indices are ignored by the linker. 
Present linkers do no type checking. 

Public Base 

This field is conditional and is identical to the public base stored in the 
public base field in the PUBDEF record. This field is only present if the 
allocation type field specifies explicit allocation. 

Public Name 

This field is a regular length prefixed name. 

Dat 

The Dat field provides up to 1024 consecutive bytes of data. If there are 
fixups, they must be emitted in a FIXUPP record that follows the COMDAT 
record. The data can be either enumerated or iterated, depending on the 
flags field. 

Notes: 

While creating addressing frames, the linker will add the COMDAT data 
to the appropriate logical segments, adjusting their sizes. At that time the 
offset at which the data will go inside the logical segment will be calculated. 
Next, the linker will create physical segments from adjusted logical segments 
reporting any 64K boundary overflows. 

If the allocation type is not explicit, COMDAT code and data is accumulated 
by the linker and broken up into segments, so that the total may exceed 64K. 

In pass two, only the selected occurrence of COMDAT data will be stored in 
the VM, fixed up and later written into the .EXE file. 
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C4H or C5H LINSYM Symbol Line Numbers Record 
Description: 

This record will be used to output numbers for functions specified via 
COMDATs. 

Record format: 


1 

2 

1 

< variable > 

2 

2 or 4 

1 

C4H 

or 

C5H 

Record 

Length 

Flags 

Symbol 

Name 

Base 

Line 

Number 

Line 

Number 

Offset 

Chk 

Sum 


<— repeated —> 


FIGURE 7.37 

COMDAT initialized communal data record. 

Flags 

This field contains three defined bits: 

01H Continuation bit. If clear, then this COMDAT record establishes a 
new instance of the COMDAT variable, otherwise the data is a contin¬ 
uation of the previous COMDAT of the symbol. 

04H Local COMDAT 


The Symbol Name Base is a length-preceded name of the base of the 
LINSYM record. 

The Line Number is an unsigned number in the range 0 to 65535. 

The Line Number Offset field is the offset relative to the base specified by 
the symbol name base. The size of this field depends on the record type. 

Notes: 

Record type C5H identical to C4H except that the Line Number Offset field 
is 4 bytes instead of 2. 

This record is used to output line numbers for functions specified via 
COMDATs. Often, the residing segment as well as the relative offsets of such 
function is unknown at compile time, in that the linker is the final arbitrator 
of such information. For such cases the compiler will generate this record 
to specify the line number/offset pairs relative to a symbolic name. 




APPENDIX 


171 


This record will also be used to discard duplicate linnum information. If 
the linker encounters two LINSYM records with matching symbolic names, 
the linker will keep the first set of linnums and discard all subsequent LINSYM 
records of that name. 
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C6H ALIAS Alias Definition Record 
Description: 

This record has been introduced to support link-time aliasing, or a method 
by which compilers or assembles may direct the linker to substitute all ref¬ 
erences to one symbol for another. 

Record format: 


1 

2 

< variable > 

< variable > 

1 (bytes) 

C6H 

Rec Len 

Alias Name 

Substitute Name 

Chk Sum 


<-repeated-> 


FIGURE 7.38 

ALIAS alias definition record. 

The Alias Name field is a regular length-preceded name of the alias symbol. 
The Substitute Name field is a regular length-preceded name of the sub¬ 
stitute symbol. 

Notes: 

The record will consist of two symbolic names: the alias symbol and the 
substitute symbol. The alias symbol behaves very much like a PUBDEF in 
that it must be unique. If a PUBDEF of an alias symbol is encountered or 
another ALIAS record with a different substitute symbol is encountered, a 
redefinition error should be emitted by the linker. 

When attempting to satisfy an external reference, if an ALIAS record whose 
alias symbol matches is found, the linker will halt the search for alias sym¬ 
bol definitions and will attempt to satisfy the reference with the substitute 
symbol. 

All ALIAS records must appear before the link pass 2 record. 
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C8H or C9H NBKPAT Named BackPatch Record 

Description: 

The Named Backpatch record is like a BAKPAT record, except that it refers 
to a COMDAT, by name, rather than an LI DATA or LEDATA record. 

Record format: 


1 

2 

1 

<var> 

2 or 4 

2 or 4 

1 (bytes) 

C8H 

Rec 

Loc 

Public 



Chk 

or 

C9H 

Length 

Type 

Name 

Offset 

Value 

Sum 


<- repeated -> 


FIGURE 7.39 

NBKPAT named backpatch record. 

LocType 

Type of location to be patched; the only valid values are: 

0 8-bit byte 

1 16-bit word 

2 32-bit dword, record type C9 only 
0x80 local COMDAT 

Public Name 

Length-preceded name of the COMDAT to back patch. 

Offset and Value 

These fields are 16-bits for record type C8, 32-bits for C9. 

The Offset specifies the location to be patched, as an offset into the COMDAT. 
The associated Value is added to the location being patched (unsigned 
addition, ignoring overflow). The Value field is fixed length (16-bit or 32- 
bit, depending on the record type) to make object module processing easier. 
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LX - Linear executable Module Format Description 

Revision codes: 

revision 1 - Library termination. 

revision 2 - Sector Align and Exepack support. 

revision 3 - Address Based linking. 

revision 4 - OS/2 2.0 PM Debugger (IBM) support. 


Revision 8 = Added ITERDATA2 definition and minor corrections 


32-bit Linear EXE Header 


00h 

DOS 2 Compatible 
EXE header 

ICh 

unused 

24h 

26h 

OEM Identifier 
OEM Info 

3Ch 

Offset to 
Linear EXE 
Header 

40h 

DOS 2.0 Stub 
Program and 
Reloc. Table 


DOS 2.0 Section 
(Discarded) 


FIGURE 7.40 

Dos 2.0 Section(Biscarded). 
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xxh 


Executable 

Info 


Module 

Info 


Loader 

Section 

Info 


Table Offset 
Info 


Linear Executable 
Module Header 
(Resident) 


FIGURE 7.41 

Linear Executable Module Header (Resident). 


Fixup Page Table 


Fixup Record 
Table 


Import Module 
Name Table 


Import Procedure 
Name Table 


Fixup Section 
(Optionally Resident) 


FIGURE 7.42 

Loader Section (Resident). 
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Object Table 


Object Page Table 


Resource Table 


Resident Name 
Table 


Entry Table 


Module Format 
Directives Table 
(Optional) 


Resident 
Directives Data 
(Optional) 

(Verify Record) 


Per-Page 

Checksum 


Loader Section 
(Resident) 


FIGURE 7.43 

Loader Section (Resident). 
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Preload Pages 


Demand Load 
Pages 


Iterated Pages 


Non-Resident 
Name Table 


Non-Resident 
Directives Data 
(Optional) 

(To be Defined) 


(Non-Resident) 


FIGURE 7.44 
Non-Resident Section. 


Debug Info 


(Not used by Loader) 


FIGURE 7.45 

Not used by the Loader. 
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LX Header 

Note: The OBJECT ITER PAGES OFF must either be 0 or set to 
the same value as DATA PAGES OFFSET in OS/2 2.0. I.e., iterated 
pages are required to be in the same section of the file as regular 
pages. 

Note: Table offsets in the Linear EXE Header may be set to zero to 
indicate that the table does not exist in the EXE file and it’s size is 
zero. 

“L” “X” = DW Signature word. 

The signature word is used by the loader to identify the 
EXE file as a valid 32-bit Linear Executable Module For¬ 
mat. “L” is low order byte. “X” is high order byte. 

B-ORD = DB Byte Ordering. 

This byte specifies the byte ordering for the linear EXE 
format. The values are: 

00H - Little Endian Byte Ordering. 

01H - Big Endian Byte Ordering. 

W-ORD = DB Word Ordering. 

This byte specifies the Word ordering for the linear EXE 
format. The values are: 

00H - Little Endian Word Ordering. 

01H - Big Endian Word Ordering. 

Format Level = DD Linear EXE Format Level. 

The Linear EXE Format Level is set to 0 for the initial 
version of the 32-bit linear EXE format. Each incompat¬ 
ible change to the linear EXE format must increment this 
value. This allows the system to recognized future EXE 
file versions so that an appropriate error message may be 
displayed if an attempt is made to load them. 

CPU Type - DW Module CPU Type. 

This field specifies the type of CPU required by this module 
to run. The values are: 

01H - 80286 or upwardly compatible CPU is required to 
execute this module. 

02H - 80386 or upwardly compatible CPU is required to 
execute this module. 

03H - 80486 or upwardly compatible CPU is required to 
execute this module. 

08 Type = DW Module OS Type. 
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OFFSET 


00h 

“L” “X”, B-ORD, W-ORD 

FORMAT LEVEL 

08h 

CPU TYPE, OS TYPE 

MODULE VERSION 

10 h 

MODULE FLAGS 

MODULE # OF PAGES 

18h 

EIP OBJECT # 

EIP 

20h 

ESP OBJECT # 

ESP 

2 8 h 

PAGE SIZE 

PAGE OFFSET SHIFT 

BOh 

FIXUP SECTION SIZE 

FIXUP SECTION CHECKSUM 

38h 

LOADER SECTION SIZE 

LOADER SECTION CHECKSUM 

40h 

OBJECT TABLE OFF 

# OBJECTS IN MODULE 

48h 

OBJECT PAGE TABLE OFF 

OBJECT ITER PAGES OFF 

50h 

RESOURCE TABLE OFFSET 

# RESOURCE TABLE ENTRIES 

58h 

RESIDENT NAME TBL OFF 

ENTRY TABLE OFFSET 

60h 

MODULE DIRECTIVES OFF 

# MODULE DIRECTIVES 

68h 

FIXUP PAGE TABLE OFF 

FIXUP RECORD TABLE OFF 

70h 

IMPORT MODULE TBL OFF 

# IMPORT MOD ENTRIES 

78h 

IMPORT PROC TBL OFF 

PER-PAGE CHECKSUM OFF 

80h 

DATA PAGES OFFSET 

# PRELOAD PAGES 

88h 

NON-RES NAME TBL OFF 

NON-RES NAME TBL LEN 

90h 

NON-RES NAME TBL CKSM 

AUTO DS OBJECT # 

98h 

DEBUG INFO OFF 

DEBUG INFO LEN 

AOh 

INSTANCE PRELOAD 

# INSTANCE DEMAND 

A8h 

HEAPSIZE 

STACKSIZE 


FIGURE 7.46 

32-bit Linear EXE Header. 
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This field specifies the type of Operating system required 
to run this module. The currently defined values are: 

00H - Unknown (any “new-format” OS) 

01H - OS/2 (default) 

02H - Windows 1 
03H - DOS 4.x 
04H - Windows 386 2 

MODULE VERSION = DD Version of the linear EXE module. 

This is useful for differentiating between revisions of dy¬ 
namic linked modules. This value is specified at link time 
by the user. 

MODULE FLAGS = DD Flag bits for the module. 

The module flag bits have the following definitions. 
0000000 lh = Default Data segment is global (DATA SIN¬ 
GLE) 

00000002h = Default Data segment is instance (DATA 
MULTIPLE) 

0Q000004h = Per-Process Library Initialization. 

The setting of this bit requires the EIP Object # and 
EIP fields to have valid values. If the EIP Object # 
and EIP fields are valid and this bit is NOT set, then 
Global Library Initialization is assumed. Setting this 
bit for an EXE file is invalid. 

00000008h = Reserved for system use. 

0000001 Oh = Internal fixups for the module have been 
applied. 

The setting of this bit in a Linear Executable Module 
indicates that each object of the module has a preferred 
load address specified in the Object Table Reloc Base 
Addr. If the module’s objects can not be loaded at 
these preferred addresses, then the relocation records 
that have been retained in the file data will be applied. 
00000020h = External fixups for the module have been 
applied. 

00000040h = Reserved for system use. 

00000080h = Reserved for system use. 

00000lOOh = Incompatible with PM windowing. 


Windows is a Registered Trademark of Microsoft Corp. 
2 ibdem 
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00000200h = Compatible with PM windowing. 
00000300h = Uses PM windowing API. 

00000400h = Reserved for system use. 

00000800h = Reserved for system use. 

OOOOlOOOh = Reserved for system use. 

00002000h = Module is not loadable. 

When the ‘Module is not loadable’ flag is set, it in¬ 
dicates that either errors were detected at link time 
or that the module is being incrementally linked and 
therefore can’t be loaded. 

00004000h = Reserved for system use. 

00038000h = Module type mask. 

OOOOOOOOh = Program module. 

A module can not contain dynamic links to other mod¬ 
ules that have the ‘program module’ type. 

00008000h = Library module. 

00018000h = Protected Memory Library module. 
00020000h = Physical Device Driver module. 

00028000h = Virtual Device Driver module. 

40000000h = Per-process Library Termination. 

The setting of this bit requires the EIP Object # and 
EIP fields to have valid values. If the EIP Object # 
and EIP fields are valid and this bit is NOT set, then 
Global Library Termination is assumed. Setting this 
bit for an EXE file is invalid. 

MODULE # PAGES = DD Physical number of pages in module. 

This field specifies the number of pages physically con¬ 
tained in this module. In other words, pages containing 
either enumerated or iterated data, not invalid or zero-fill 
pages. These pages are contained in the ‘preload pages’, 
‘demand load pages’ and ‘iterated data pages’ sections of 
the linear EXE module. This is used to determine the size 
of the other physical page based tables in the linear EXE 
module. 

EIP OBJECT # = DD The Object number to which the Entry 

Address is relative. 

This specifies the object to which the Entry Address is rel¬ 
ative. This must be a nonzero value for a program module 
to be correctly loaded. A zero value for a library module 



182 


APPENDIX 


indicates that no library entry routine exists. If this value 
is zero, then both the Per-process Library Initialization bit 
and the Per-process Library Termination bit must be clear 
in the module flags, or else the loader will fail to load the 
module. Further, if the Per-process Library Termination 
bit is set, then the object to which this field refers must be 
a 32-bit object (i.e., the Big/Default bit must be set in the 
object flags; see below). 

EIP = DD Entry Address of module. 

The Entry Address is the starting address for program mod¬ 
ules and the library initialization and Library termination 
address for library modules. 

ESP OBJECT # = DD The Object number to which the ESP is 
relative. 

This specifies the object to which the starting ESP is rela¬ 
tive. This must be a nonzero value for a program module 
to be correctly loaded. This field is ignored for a library 
module. 

ESP = DD Starting stack address of module. 

The ESP defines the starting stack pointer address for pro¬ 
gram modules. A zero value in this field indicates that the 
stack pointer is to be initialized to the highest address/offset 
in the object. This field is ignored for a library module. 
PAGE SIZE = DD The size of one page for this system. 

This field specifies the page size used by the linear EXE 
format and the system. For the initial version of this linear 
EXE format the page size is 4Kbytes. (The 4K page size 
is specified by a value of 4096 in this field.) 

PAGE OFFSET SHIFT = DD The shift left bits for page offsets. 
This field gives the number of bit positions to shift left when 
interpreting the Object Page Table entries’ page offset field. 
This determines the alignment of the page information in 
the file. For example, a value of 4 in this field would align 
all pages in the Data Pages and Iterated Pages sections on 
16 byte (paragraph) boundaries. A Page Offset Shift of 9 
would align all pages on a 512 byte (disk sector) basis. All 
other offsets are byte aligned. 

A page might not start at the next available alignment boundary. 
Extra padding is acceptable between pages as long as each page 
starts on an alignment boundary. For example, several align¬ 
ment boundaries may be skipped in order to start a frequently 
accessed page on a sector boundary. 
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FIXUP SECTION SIZE = DD Total size of the fixup information in 
bytes. 

This includes the following 4 tables: 

- Fixup Page Table 

- Fixup Record Table 

- Import Module name Table 

- Import Procedure Name Table 

FIXUP SECTION CHECKSUM = DD Checksum for fixup informa¬ 
tion. 

This is a cryptographic checksum covering all of the fixup in¬ 
formation. The checksum for the fixup information is kept 
separate because the fixup data is not always loaded into main 
memory with the ‘loader section’. If the checksum feature is 
not implemented, then the linker will set these fields to zero. 

LOADER SECTION SIZE = DD Size of memory resident tables. 

This is the total size in bytes of the tables required to be mem¬ 
ory resident for the module, while the module is in use. This 
total size includes all tables from the Object Table down to and 
including the Per-Page Checksum Table. 

LOADER SECTION CHECKSUM = DD Checksum for loader sec¬ 
tion. 

This is a cryptographic checksum covering all of the loader sec¬ 
tion information. If the checksum feature is not implemented, 
then the linker will set these fields to zero. 

OBJECT TABLE OFF = DD Object Table offset. 

This offset is relative to the beginning of the linear EXE header. 

# OBJECTS IN MODULE = DD Object Table Count. 

This defines the number of entries in Object Table. 

OBJECT PAGE TABLE OFFSET = DD Object Page Table offset 

This offset is relative to the beginning of the linear EXE header. 

OBJECT ITER PAGES OFF = DD Object Iterated Pages offset. 

This offset is relative to the beginning of the EXE file. 

RESOURCE TABLE OFF = DD Resource Table offset. 

This offset is relative to the beginning of the linear EXE header. 
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# RESOURCE TABLE ENTRIES = DD Number of entries in Re¬ 
source Table. 

RESIDENT NAME TBL OFF = DD Resident Name Table offset. 

This offset is relative to the beginning of the linear EXE header. 
ENTRY TBL OFF = DD Entry Table offset. 

This offset is relative to the beginning of the linear EXE header. 

MODULE DIRECTIVES OFF = DD Module Format Directives Ta¬ 
ble offset. 

This offset is relative to the beginning of the linear EXE header. 

# MODULE DIRECTIVES = DD Number of Module Format Direc¬ 
tives in the Table. 

This field specifies the number of entries in the Module Format 
Directives Table. 

FIXUP PAGE TABLE OFF = DD Fixup Page Table offset. 

This offset is relative to the beginning of the linear EXE header. 

FIXUP RECORD TABLE OFF = DD Fixup Record Table Offset 

This offset is relative to the beginning of the linear EXE header. 

IMPORT MODULE TBL OFF = DD Import Module Name Table 
offset. 

This offset is relative to the beginning of the linear EXE header. 

# IMPORT MOD ENTRIES = DD The number of entries in the 
Import Module Name Table. 

IMPORT PROC TBL OFF = DD Import Procedure Name Table off¬ 
set. 

This offset is relative to the beginning of the linear EXE header. 

PER-PAGE CHECKSUM OFF = DD Per-Page Checksum Table off¬ 
set. 

This offset is relative to the beginning of the linear EXE header. 
DATA PAGES OFFSET = DD Data Pages Offset. 

This offset is relative to the beginning of the EXE file. 

# PRELOAD PAGES = DD Number of Preload pages for this module. 
Note that OS/2 2.0 does not respect the preload of pages as specified 
in the executable file for performance reasons. 

NON-RES NAME TBL OFF = DD Non-Resident Name Table offset. 
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This offset is relative to the beginning of the EXE file. 

NON-RES NAME TBL LEN = DD Number of bytes in the Non¬ 
resident name table. 

NON-RES NAME TBL CKSM = DD Non-Resident Name Table 
Checksum. 

This is a cryptographic checksum of the Non-Resident Name 
Table. 

AUTO DS OBJECT # = DD The Auto Data Segment Object number. 

This is the object number for the Auto Data Segment used by 
16-bit modules. This field is supported for 16-bit compatibility 
only and is not used by 32-bit modules. 

DEBUG INFO OFF = DD Debug Information offset. 

This offset is relative to the beginning of the file. 

Note: Earlier versions of this doc stated that this offset was 
from the linear EXE header - this is incorrect. 

DEBUG INFO LEN = DD Debug Information length. 

The length of the debug information in bytes. 

# INSTANCE PRELOAD = DD Instance pages in preload section. 

The number of instance data pages found in the preload section. 

# INSTANCE DEMAND = DD Instance pages in demand section. 

The number of instance data pages found in the demand section. 

HEAPSIZE = DD Heap size added to the Auto DS Object. 

The heap size is the number of bytes added to the Auto Data 
Segment by the loader. This field is supported for 16-bit com¬ 
patibility only and is not used by 32-bit modules. 

STACKSIZE = DD Stack size. 

The stack size is the number of bytes specified by: 

1. size of a segment with combine type stack 

2. STACKSIZE in the .DEF file 

3. /STACK link option 

The stacksize may be zero. 

Note: Stack sizes with byte 2 equal to 02 or 04 (e.g. 
00020000h, 1104111 lh, 0f02ffffh) should be avoided 
for programs that will run on OS/2 2.0. 
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Program (EXE) startup registers and Library entry registers 

Program startup registers are defined as follows. 

EIP = Starting program entry address. 

ESP = Top of stack address. 

CS = Code selector for base of linear address space. 

DS = ES = SS = Data selector for base of linear address space. 

FS = Data selector of base of Thread Information Block (TIB). 

GS = 0. 

EAX = EBX = 0. 

ECX = EDX = 0. 

ESI = EDI = 0. 

EBP = 0. 

[ESP+0] = Return address to routine which calls DosExit(l,EAX). 
[ESP+4] = Module handle for program module. 

[ESP+8] = Reserved. 

[ESP+12] = Environment data object address. 

[ESP+16] = Command line linear address in environment data object. 

Library initialization registers are defined as follows. 

EIP = Library entry address. 

ESP = User program stack. 

CS = Code selector for base of linear address space. 

DS = ES = SS = Data selector for base of linear address space. 

FS = Data selector of base of Thread Information Block (TIB). 

GS = 0. 

EAX = EBX = 0. 

ECX = EDX = 0. 
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ESI = EDI = 0. 

EBP = 0. 

[ESP+0] = Return address to system, (EAX) = return code. 

[ESP+4] = Module handle for library module. 

[ESP+8] = 0 (Initialization) 

Note that a 32-bit library may specify that its entry address is in a 16-bit 
code object. In this case, the entry registers are the same as for entry to a 
library using the Segmented EXE format. These are documented elsewhere. 
This means that a 16-bit library may be relinked to take advantage of the 
benefits of the Linear EXE format (notably, efficient paging). 

Library termination registers are defined as follows. 

EIP = Library entry address. 

ESP = User program stack. 

CS = Code selector for base of linear address space. 

DS = ES = SS = Data selector for base of linear address space. 

FS = Data selector of base of Thread Information Block (TIB). 

GS = 0. 


EAX = EBX = 0. 
ECX = EDX = 0. 
ESI = EDI = 0. 
EBP = 0. 


[ESP+0] = Return address to system. 

[ESP+4] = Module handle for library module. 

[ESP+8] = 1 (Termination) 

Note that Library termination is not allowed for libraries with 16-bit entries. 

Object Table 

The number of entries in the Object Table is given by the # Objects in 
Module field in the linear EXE header. Entries in the Object Table are 
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numbered starting from one. 

Each Object Table entry has the following format: 

OOh 

08 

lOh 

FIGURE 7.47 
Object Table. 


VIRTUAL SIZE 

RELOC BASE ADDR 

OBJECT FLAGS 

PAGE TABLE INDEX 

# PAGE TABLE ENTRIES 

RESERVED 


VIRTUAL SIZE = DD Virtual memory size. 

This is the size of the object that will be allocated when the 
object is loaded. The object data length must be less than or 
equal to the total size of the pages in the EXE file for the object. 
This memory size must also be large enough to contain all of 
the iterated data and uninitialized data in the EXE file. 

RELOC BASE ADDR = DD Relocation Base Address. 

The relocation base address the object is currently relocated 
to. If the internal relocation fixups for the module have been 
removed, this is the address the object will be allocated at by 
the loader. 

OBJECT FLAGS = DW Flag bits for the object. 

The object flag bits have the following definitions. 

000 lh = Readable Object. 

0002h = Writable Object. 

0004h = Executable Object. 

The readable, writable and executable flags provide 
support for all possible protections. In systems where 
all of these protections are not supported, the loader 
will be responsible for making the appropriate protec¬ 
tion match for the system. 

0008h = Resource Object. 

001 Oh = Discardable Object. 

0020h = Object is Shared. 
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0040h = Object has Preload Pages. 

0080h = Object has Invalid Pages. 

OlOOh = Object has Zero Filled Pages. 

0200h = Object is Resident (valid for VDDs, PDDs only). 

0300h = Object is Resident & Contiguous (VDDs, PDDs 

only). 

0400h = Object is Resident & ’long-lockable’ (VDDs, 

PDDs only). 

0800h = Reserved for system use. 

lOOOh = 16:16 Alias Required (80x86 Specific). 

2000h = Big/Default Bit Setting (80x86 Specific). 

The ‘big/default’ bit, for data segments, controls the 
setting of the Big bit in the segment descriptor. (The 
Big bit, or B-bit, determines whether ESP or SP is 
used as the stack pointer.) For code segments, this 
bit controls the setting of the Default bit in the seg¬ 
ment descriptor. (The Default bit, or D-bit, deter¬ 
mines whether the default word size is 32-bits or 16- 
bits. It also affects the interpretation of the instruction 
stream.) 

4000h = Object is conforming for code (80x86 Specific). 

8000h = Object I/O privilege level (80x86 Specific). 

Only used for 16:16 Alias Objects. 

PAGE TABLE INDEX = DD Object Page Table Index. 

This specifies the number of the first object page table entry 
for this object. The object page table specifies where in the 
EXE file a page can be found for a given object and specifies 
per-page attributes. 

The object table entries are ordered by logical page in the object 
table. In other words the object table entries are sorted based 
on the object page table index value. 

# PAGE TABLE ENTRIES = DD # of object page table entries for 
this object. 

Any logical pages at the end of an object that do not have an 
entry in the object page table associated with them are handled 
as zero filled or invalid pages by the loader. 

When the last logical pages of an object are not specified with 
an object page table entry, they are treated as either zero filled 
pages or invalid pages based on the last entry in the object page 
table for that object. If the last entry was neither a zero filled or 
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invalid page, then the additional pages are treated as zero filled 
pages. 

RESERVED = DD Reserved for future use. Must be set to zero. 


Object Page Table 

The Object page table provides information about a logical page in an 
object. A logical page may be an enumerated page, a pseudo page or an 
iterated page. The structure of the object page table in conjunction with 
the structure of the object table allows for efficient access of a page when a 
page fault occurs, while still allowing the physical page data to be located 
in the preload page, demand load page or iterated data page sections in the 
linear EXE module. The logical page entries in the Object Page Table are 
numbered starting from one. The Object Page Table is parallel to the Fixup 
Page Table as they are both indexed by the logical page number. 

Each Object Page Table entry has the following format: 


63 


32 31 


16 15 


00 h 


PAGE DATA OFFSET 


DATA SIZE 


FLAGS 


FIGURE 7.48 

Object Page Table Entry. 


PAGE DATA OFFSET = DD Offset to the page data in the EXE file. 

This field, when bit shifted left by the PAGE OFFSET SHIFT 
from the module header, specifies the offset from the beginning 
of the Preload Page section of the physical page data in the EXE 
file that corresponds to this logical page entry. The page data 
may reside in the Preload Pages, Demand Load Pages or the 
Iterated Data Pages sections. 

A page might not start at the next available alignment boundary. 
Extra padding is acceptable between pages as long as each page 
starts on an alignment boundary. For example, several align¬ 
ment boundaries may be skipped in order to start a frequently 
accessed page on a sector boundary. 

If the FLAGS held specifies that this is a Zero-Filled page then 
the PAGE DATA OFFSET held will contain a 0. 

If the logical page is specihed as an iterated data page, as in¬ 
dicated by the FLAGS held, then this held specihes the offset 
into the Iterated Data Pages section. 
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The logical page number (Object Page Table index), is used to 
index the Fixup Page Table to find any fixups associated with 
the logical page. 

DATA SIZE = DW Number of bytes of data for this page. 

This field specifies the actual number of bytes that represent 
the page in the file. If the PAGE SIZE field from the module 
header is greater than the value of this field and the FLAGS 
field indicates a Legal Physical Page, the remaining bytes are 
to be filled with zeros. If the FLAGS field indicates an Iterated 
Data Page, the iterated data records will completely fill out the 
remainder. 

FLAGS = DW Attributes specifying characteristics of this logical 
page. 

The bit definitions for this word field follow, 

OOh = Legal Physical Page in the module (Offset 
from Preload Page Section). 

01 h = Iterated Data Page (Offset from Iterated Data 
Pages Section). 

02h = Invalid Page (zero). 

03h = Zero Filled Page (zero). 

04h = Range of Pages. 

05h = Compressed Page (Offset from Preload Pages 

Section). 


Resource Table 

The resource table is an array of resource table entries. Each resource 
table entry contains a type ID and name ID. These entries are used to locate 
resource objects contained in the Object table. The number of entries in the 
resource table is defined by the Resource Table Count located in the linear 
EXE header. More than one resource may be contained within a single 
object. Resource table entries are in a sorted order, (ascending, by Resource 
Name ID within the Resource Type ID). This allows the DosGetResource 
API function to use a binary search when looking up a resource in a 32-bit 
module instead of the linear search being used in the current 16-bit module. 
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Each resource entry has the following format: 


00h 

TYPE ID 

NAME ID 


04h 

RESOURCE SIZE 


08h 

OBJECT 

OFFSET 


FIGURE 7.49 
Resource Table. 


TYPE ID = DW Resource type ID. 


The type of resources are: 


Olh 

= 

RT_POINTER 

02h 

= 

RT_BITMAP 

03h 

= 

RT.MENU 

04h 

= 

RT_DIALOG 

05h 

= 

RT_STRING 

06h 

= 

RT_FONTDIR 

07h 

= 

RT_FONT 

08h 

= 

RT_ACCELTABLE 

09h 

= 

RT_RCDATA 

OAh 

= 

RT_MESSAGE 

OBh 

= 

RT_DLGINCLUDE 

OCh 

= 

RT_VKEYTBL 

ODh 

- 

RT_KEYTBL 

OEh 

= 

RT_CHARTBL 

OFh 

- 

RT_DISPLAYINFO 

lOh 

= 

RT_FKASHORT 

llh 

= 

RT_FKALONG 

12h 

= 

RT_HELPTABLE 


= mouse pointer shape 
= bitmap 
= menu template 
= dialog template 
= string tables 
= font directory 
= font 

= accelerator tables 
- binary data 
= error msg tables 
= dialog include file name 
= key to vkey tables 
= key to UGL tables 
= glyph to character tables 
= screen display information 
= function key area short form 
= function key area long form 
= Help table for Cary Help 
manager 
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13h = RT_HELPSUBTABLE = Help subtable for Cary Help 

manager 

14h = RT_FDDIR = DBCS uniq/font driver directory 

15h = RT_FD = DBCS uniq/font driver 


NAME ID = DW An ID used as a name for the resource when referred 
to. 

RESOURCE SIZE = DD The number of bytes the resource consists 
of. 

OBJECT = DW The number of the object which contains the re¬ 
source. 

OFFSET = DD The offset within the specified object where the re¬ 
source begins. 


Resident or Non-resident Name Table Entry 

The resident and non-resident name tables define the ASCII names and 
ordinal numbers for exported entries in the module. In addition the first entry 
in the resident name table contains the module name. These tables are used 
to translate a procedure name string into an ordinal number by searching for 
a matching name string. The ordinal number is used to locate the entry point 
information in the entry table. 

The resident name table is kept resident in system memory while the 
module is loaded. It is intended to contain the exported entry point names that 
are frequently dynamically linked to by name. Non-resident names are not 
kept in memory and are read from the EXE file when a dynamic link reference 
is made. Exported entry point names that are infrequently dynamically linked 
to by name or are commonly referenced by ordinal number should be placed 
in the non-resident name table. The trade off made for references by name 
is performance vs memory usage. 

Import references by name require these tables to be searched to obtain the 
entry point ordinal number. Import references by ordinal number provide 
the fastest lookup since the search of these tables is not required. 

Installable File Systems, Physical Device Drivers, and Virtual Device 
Drivers are closed after the file is loaded. Any reference to the non-resident 
name table after this time will fail. 

The strings are CASE SENSITIVE and are NOT NULL TERMINATED. 
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Each name table entry has the following format: 


OOh 


LEN 


ASCII STRING 


ORDINAL # 


FIGURE 7.50 

Resident or Non-resident Name Table Entry. 


LEN = DB String Length. 

This defines the length of the string in bytes. A zero length 
indicates there are no more entries in table. The length of each 
ascii name string is limited to 255 characters. 

The high bit in the LEN field (bit 7) is defined as an Overload 
bit. This bit signifies that additional information is contained 
in the linear EXE module and will be used in the future for 
parameter type checking. 

ASCII STRING - DB ASCII String. 

This is a variable length string with it’s length defined in bytes 
by the LEN field. The string is case sensitive and is not null 
terminated. 

ORDINAL # = DW Ordinal number. 

The ordinal number in an ordered index into the entry table for 
this entry point. 

Entry Table 

The entry table contains object and offset information that is used to resolve 
fixup references to the entry points within this module. Not all entry points 
in the entry table will be exported, some entry points will only be used within 
the module. An ordinal number is used to index into the entry table. The 
entry table entries are numbered starting from one. 

The list of entries are compressed into ‘bundles’, where possible. The 
entries within each bundle are all the same size. A bundle starts with a 
count field which indicates the number of entries in the bundle. The count 
is followed by a type field which identifies the bundle format. This provides 
both a means for saving space as well as a mechanism for extending the 
bundle types. 

The type field allows the definition of 256 bundle types. The following 
bundle types will initially be defined: 
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Unused Entry. 

16-bit Entry. 

286 Call Gate Entry. 

32-bit Entry. 

Forwarder Entry. 

The bundled entry table has the following format: 


OOh 


CNT 


TYPE 


BUNDLE INFO . . 


FIGURE 7.51 
Entry Table 


CNT = DB Number of entries. 

This is the number of entries in this bundle. 

A zero value for the number of entries identifies the end of the 
entry table. There is no further bundle information when the 
number of entries is zero. In other words the entry table is 
terminated by a single zero byte. 

TYPE = DB Bundle type. 

This defines the bundle type which determines the contents of 
the BUNDLE INFO. 


The follow types are defined: 

OOh = Unused Entry. 

Olh = 16-bit Entry. 

02h = 286 Call Gate Entry. 

03h = 32-bit Entry. 

04h = Forwarder Entry. 

80h = Parameter Typing Information Present. 

This bit signifies that additional information is con¬ 
tained in the linear EXE module and will be used in 
the future for parameter type checking. 
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The following is the format for each bundle type. 

OOh CNT TYPE 

CNT = DB Number of entries. 

This is the number of unused entries to skip. 
TYPE = DB 0 (Unused Entry) 


OOh 

CNT 

TYPE 

OBJECT 

04h 

FLAGS 

OFFSET 


07h 






CNT = DB Number of entries, 
beginitemize 

This is the number of 16-bit entries in this bundle. The flags 
and offset value are repeated this number of times. 

TYPE - DB 1 (16-bit Entry) 

OBJECT = DW Object number. 

This is the object number for the entries in this bundle. 
FLAGS = DB Entry flags. 

These are the flags for this entry point. They have the 
following definition. 

Olh = Exported entry flag. 

F8h = Parameter word count mask. 

OFFSET = DW Offset in object. 

This is the offset in the object for the entry point defined 
at this ordinal number. 
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00h 

CNT 

TYPE 

OBJECT 


04h 

FLAGS 

OFFSET 

CALLGATE 

09h 





CNT = DB Number of entries. 

This is the number of 286 call gate entries in this bundle. The 
flags, callgate, and offset value are repeated this number of 
times. 

TYPE = DB 2 (286 Call Gate Entry) 

The 286 Call Gate Entry Point type is needed by the loader only 
if ring 2 segments are to be supported. 286 Call Gate entries 
contain 2 extra bytes which are used by the loader to store an 
LDT callgate selector value. 

OBJECT = DW Object number. 

This is the object number for the entries in this bundle. 

FLAGS = DB Entry flags. 

These are the flags for this entry point. They have the following 
definition. 

Olh = Exported entry flag. 

F8h = Parameter word count mask. 

OFFSET = DW Offset in object. 

This is the offset in the object for the entry point defined at this 
ordinal number. 

CALLGATE = DW Callgate selector. 

The callgate selector is a reserved field used by the loader to 
store a call gate selector value for references to ring 2 entry 
points. When a ring 3 reference to a ring 2 entry point is made, 
the callgate selector with a zero offset is place in the relocation 
fixup address. The segment number and offset in segment is 
placed in the LDT callgate. 
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OOh 

CNT 

TYPE 

OBJECT 


04h 

FLAGS 

OFFSET 

09h 




CNT = DB Number of entries. 

This is the number of 32-bit entries in this bundle. The flags 
and offset value are repeated this number of times. 

TYPE = DB 3 (32-bit Entry) 

The 32-bit Entry type will only be defined by the linker when 
the offset in the object can not be specified by a 16-bit offset. 

OBJECT = DW Object number. 

This is the object number for the entries in this bundle. 

FLAGS = DB Entry flags. 

These are the flags for this entry point. They have the following 
definition. 

Olh = Exported entry flag. 

F8h = Parameter dword count mask. 

OFFSET = DD Offset in object. 

This is the offset in the object for the entry point defined at this 
ordinal number. 


OOh 

CNT 

TYPE 

RESERVED 


04h 

FLAGS 

MOD ORD# 

OFFSET / ORDNUM 

09h 





CNT = DB Number of entries. 






APPENDIX 


199 


This is the number of forwarder entries in this bundle. The 
FLAGS, MOD ORD#, and OFFSET/ORDNUM values are re¬ 
peated this number of times. 

TYPE = DB 4 (Forwarder Entry) 

RESERVED = DW 0 

This field is reserved for future use. 

FLAGS = DB Forwarder flags. 

These are the flags for this entry point. They have the following 
definition. 

Olh = Import by ordinal. 

F7h = Reserved for future use; should be zero. 

MOD ORD# = DW Module Ordinal Number 

This is the index into the Import Module Name Table for this 
forwarder. 

OFFSET / ORDNUM = DD Procedure Name Offset or Import Or¬ 
dinal Number 

If the FLAGS field indicates import by ordinal, then this field 
is the ordinal number into the Entry Table of the target module, 
otherwise this field is the offset into the Procedure Names Table 
of the target module. 

A Forwarder entry (type = 4) is an entry point whose value is an imported 
reference. When a load time fixup occurs whose target is a forwarder, the 
loader obtains the address imported by the forwarder and uses that imported 
address to resolve the fixup. 

A forwarder may refer to an entry point in another module which is itself a 
forwarder, so there can be a chain of forwarders. The loader will traverse the 
chain until it finds a non-forwarded entry point which terminates the chain 
, and use this to resolve the original fixup. Circular chains are detected by 
the loader and result in a load time error. A maximum of 1024 forwarders is 
allowed in a chain; more than this results in a load time error. 

Forwarders are useful for merging and recombining API calls into differ¬ 
ent sets of libraries, while maintaining compatibility with applications. For 
example, if one wanted to combine MONCALLS, MOUCALLS, and VIO- 
CALLS into a single libraries, one could provide entry points for the three 
libraries that are forwarders pointing to the common implementation. 
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Module Format Directives Table 

The Module Format Directives Table is an optional table that allows ad¬ 
ditional options to be specified. It also allows for the extension of the linear 
EXE format by allowing additional tables of information to be added to the 
linear EXE module without affecting the format of the linear EXE header. 
Likewise, module format directives provide a place in the linear EXE module 
for Temporary tables’ of information, such as incremental linking informa¬ 
tion and statistic information gathered on the module. When there are no 
module format directives for a linear EXE module, the fields in the linear 
EXE header referencing the module format directives table are zero. 

Each Module Format Directive Table entry has the following format: 


OOh 


DIRECT # 


DATA LEN 


DATA OFFSET 


FIGURE 7.52 

Module Format Directive Table. 


DIRECT # = DW Directive number. 

The directive number specifies the type of directive defined. 
This can be used to determine the format of the information in 
the directive data. The following directive numbers have been 
defined: 

8000h = Resident Flag Mask. 

Directive numbers with this bit set indicate that the 
directive data is in the resident area and will be kept 
resident in memory when the module is loaded. 

800 lh = Verify Record Directive. (Verify record is a resi¬ 
dent table.) 

0002h = Language Information Directive. (This is a non¬ 
resident table.) 

0003h = Co-Processor Required Support Table. 

0004h = Thread State Initialization Directive. 

0005h = C Set ++ Browse Information. 

Additional directives can be added as needed in the future, as 
long as they do not overlap previously defined directive num¬ 
bers. 

DATA LEN = DW Directive data length. 
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This specifies the length in byte of the directive data for this 
directive number. 

DIRECTIVE OFFSET = DD Directive data offset. 

This is the offset to the directive data for this directive number. 
It is relative to beginning of linear EXE header for a resident 
table, and relative to the beginning of the EXE file for non¬ 
resident tables. 

Verify Record Directive Table 

The Verify Record Directive Table is an optional table. It maintains a 
record of the pages in the EXE file that have been fixed up and written back 
to the original linear EXE module, along with the module dependencies used 
to perform these fixups. This table provides an efficient means for verifying 
the virtual addresses required for the fixed up pages when the module is 
loaded. 

Each Verify Record entry has the following format: 


00h 

#OF ENTRY 


02h 

MOD ORD # 

VERSION 

MOD # OBJ 

08h 

OBJECT # 

BASE ADDR 

VIRTUAL 

OEh 





FIGURE 7.53 
Verify Record Table. 


# OF ENTRY = DW Number of module dependencies. 

This field specifies how many entries there are in the verify 
record directive table. This is equal to the number of modules 
referenced by this module. 

MOD ORD # = DW Ordinal index into the Import Module Name 
Table. 

This value is an ordered index in to the Import Module Name 
Table for the referenced module. 
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VERSION = DW Module Version. 


This is the version of the referenced module that the fixups were 
originally performed. This is used to insure the same version 
of the referenced module is loaded that was fixed up in this 
module and therefore the fixups are still correct. This requires 
the version number in a module to be incremented anytime the 
entry point offsets change. 

MOD # OBJ = DW Module # of Object Entries. 


This field is used to identify the number of object verify entries 
that follow for the referenced module. 

OBJECT # = DW Object # in Module. 


This field specifies the object number in the referenced module 
that is being verified. 

BASE ADDR = DW Object load base address. 


This is the address that the object was loaded at when the fixups 
were performed. 

VIRTUAL = DW Object virtual address size. 


This field specifies the total amount of virtual memory required 
for this object. 


Per»Page Checksum 

The Per-Page Checksum table provides space for a cryptographic check¬ 
sum for each physical page in the EXE file. 

The checksum table is arranged such that the first entry in the table corre¬ 
sponds to the first logical page of code/data in the EXE file (usually a preload 
page) and the last entry corresponds to the last logical page in the EXE file 
(usually a iterated data page). 
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Logical 


Logical 


Logical 


Page 


Page 


Page 


# 1 

# 2 


# n 


CHECKSUM 


CHECKSUM 


CHECKSUM 


FIGURE 7.54 
Per-Page Checksum. 

CHECKSUM = DD Cryptographic checksum. 

Fixup Page Table 

The Fixup Page Table provides a simple mapping of a logical page number 
to an offset into the Fixup Record Table for that page. 

This table is parallel to the Object Page Table, except that there is one 
additional entry in this table to indicate the end of the Fixup Record Table. 
The format of each entry is: 


Logical 


Logical 


Logical 



This is equal to: 

Offset for page # n + Size 
of fixups for page # n 


FIGURE 7.55 
Fixup Page Table. 
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OFFSET FOR PAGE # = DD Offset for fixup record for this page. 

This field specifies the offset, from the beginning of the fixup 
record table, to the first fixup record for this page. 

OFF TO END OF FIXUP REC = DD Offset to the end of the fixup 
records. 

This field specifies the offset' following the last fixup record in 
the fixup record table. This is the last entry in the fixup page 
table. 

The fixup records are kept in order by logical page in the fixup 
record table. This allows the end of each page’s fixup records 
is defined by the offset for the next logical page’s fixup records. 
This last entry provides support of this mechanism for the last 
page in the fixup page table. 

Fixup Record Table 

The Fixup Record Table contains entries for all fixups in the linear EXE 
module. The fixup records for a logical page are grouped together and kept 
in sorted order by logical page number. The fixups for each page are further 
sorted such that all external fixups and internal selector/pointer fixups come 
before internal non-selector/non-pointer fixups. This allows the loader to 
ignore internal fixups if the loader is able to load all objects at the addresses 
specified in the object table. 

Each relocation record has the following format: 


OOh 

03h/04h 


SRC 

FLAGS 

SRCOFF/CNT * 


TARGET DATA * 

SRCOFF1 @ 


SRCOFFn @ 


* These fields are variable size. 
@ These fields are optional. 

FIGURE 7.56 
Fixup Record Table. 


SRC = DB Source type. 
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The source type specifies the size and type of the fixup to be 
performed on the fixup source. The source type is defined as 
follows: 

OFh = Source mask. 

OOh = Byte fixup (8-bits). 

Olh = (undefined). 

02h = 16-bit Selector fixup (16-bits). 

03h = 16:16 Pointer fixup (32-bits). 

04h = (undefined). 

05h = 16-bit Offset fixup (16-bits). 

06h - 16:32 Pointer fixup (48-bits). 

07h = 32-bit Offset fixup (32-bits). 

08h = 32-bit Self-relative offset fixup (32-bits). 
lOh = Fixup to Alias Flag. 

When the ‘Fixup to Alias’ Flag is set, the source fixup 
refers to the 16:16 alias for the object. This is only valid 
for source types of 2, 3, and 6. For fixups such as this, the 
linker and loader will be required to perform additional 
checks such as ensuring that the target offset for this fixup 
is less than 64K. 

20h = Source List Flag. 

When the ‘Source List’ Flag is set, the SRCOFF field is 
compressed to a byte and contains the number of source 
offsets, and a list of source offsets follows the end of fixup 
record (after the optional additive value). 

FLAGS = DB Target Flags. 

The target flags specify how the target information is inter¬ 
preted. The target flags are defined as follows. 

03h = Fixup target type mask. 

OOh = Internal reference. 

Olh = Imported reference by ordinal. 

02h = Imported reference by name. 

03h = Internal reference via entry table. 

04h = Additive Fixup Flag. 

When set, an additive value trails the fixup record (before 
the optional source offset list). 
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08h = Reserved. Must be zero. 

lOh = 32-bit Target Offset Flag. 

When set, the target offset is 32-bits, otherwise it is 16-bits. 

20h = 32-bit Additive Fixup Flag. 

When set, the additive value is 32-bits, otherwise it is 16- 
bits. 

40h = 16-bit Object Number/Module Ordinal Flag. 

When set, the object number or module ordinal number is 
16-bits, otherwise it is 8-bits. 

80h = 8-bit Ordinal Flag. 

When set, the ordinal number is 8-bits, otherwise it is 16- 
bits. 

SRCOFF = DW/CNT = DB Source offset or source offset list count. 

This field contains either an offset or a count depending on 
the Source List Flag. If the Source List Flag is set, a list of 
source offsets follows the additive field and this field contains 
the count of the entries in the source offset list. Otherwise, 
this is the single source offset for the fixup. Source offsets are 
relative to the beginning of the page where the fixup is to be 
made. 

Note that for fixups that cross page boundaries, a separate fixup 
record is specified for each page. An offset is still used for the 
2nd page but it now becomes a negative offset since the fixup 
originated on the preceding page. (For example, if only the last 
one byte of a 32-bit address is on the page to be fixed up, then 
the offset would have a value of -3.) 

TARGET DATA = Target data for fixup. 

The format of the TARGET DATA is dependent upon target 
flags. 

SRCOFF 1 - SRCOFFn = DW[] Source offset list. 

This list is present if the Source List Flag is set in the Target 
Flags field. The number of entries in the source offset list 
is defined in the SRCOFF/CNT field. The source offsets are 
relative to the beginning of the page where the fixups are to be 
made. 
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00h 

SRC 

FLAGS 

SRCOFF/CNT * 


03h/04h 

OBJECT * 

TRGOFF * @ 


SRCOFF1 @ 


SRCOFFn @ 




* These fields are variable size. 
@ These fields are optional. 


FIGURE 7.57 
Internal Fixup Record. 


OBJECT = D[BIW] Target object number. 

This field is an index into the current module’s Object Table 
to specify the target Object. It is a Byte value when the ‘16- 
bit Object Number/Module Ordinal Flag’ bit in the target flags 
field is clear and a Word value when the bit is set. 

TRGOFF = D[WID] Target offset. 

This field is an offset into the specified target Object. It is not 
present when the Source Type specifies a 16-bit Selector fixup. 
It is a Word value when the ‘32-bit Target Offset Flag’ bit in 
the target flags field is clear and a Dword value when the bit is 
set. 


MOD ORD # = D[BIW] Ordinal index into the Import Module Name 
Table. 

This value is an ordered index in to the Import Module Name 
Table for the module containing the procedure entry point. It is 
a Byte value when the ‘16-bit Object Number/Module Ordinal’ 
Flag bit in the target flags field is clear and a Word value when 
the bit is set. The loader creates a table of pointers with each 
pointer in the table corresponds to the modules named in the 
Import Module Name Table. This value is used by the loader to 
index into this table created by the loader to locate the referenced 
module. 


IMPORT ORD = D[BIWID] Imported ordinal number. 
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OOh 

03h/04h 


SRC 

FLAGS 

SRCOFF/CNT * 


MOD ORD# * 

IMPORT ORD * 

ADDITIVE * @ 

SRCOFF1 @ 


SRCOFFn @ 


* These fields are variable size. 
@ These fields are optional. 


FIGURE 7.58 

Import by Ordinal Fixup Record. 


This is the imported procedure’s ordinal number. It is a Byte 
value when the ‘8-bit Ordinal’ bit in the target flags field is set. 
Otherwise it is a Word value when the ‘32-bit Target Offset 
Flag’ bit in the target flags field is clear and a Dword value 
when the bit is set. 

ADDITIVE - D[WID] Additive fixup value. 

This field exists in the fixup record only when the ‘Additive 
Fixup Flag’ bit in the target flags field is set. When the ‘Additive 
Fixup Flag’ is clear the fixup record does not contain this field 
and is immediately followed by the next fixup record (or by the 
source offset list for this fixup record). 

This value is added to the address derived from the target entry 
point. This field is a Word value when the ‘32-bit Additive Flag’ 
bit in the target flags field is clear and a Dword value when the 
bit is set. 


MOD ORD # = D[BIW] Ordinal index into the Import Module Name 
Table. 

This value is an ordered index in to the Import Module Name 
Table for the module containing the procedure entry point. It is 
a Byte value when the ‘16-bit Object Number/Module Ordinal’ 
Flag bit in the target flags field is clear and a Word value when 
the bit is set. The loader creates a table of pointers with each 
pointer in the table corresponds to the modules named in the 
Import Module Name Table. This value is used by the loader to 
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OOh 

03h/ 

04h 


SRC 

FLAGS 

SRCOFF/CNT * 


MOD ORD# * 

PROCEDURE NAME OFFSET * 

ADDITIVE * @ 

SRCOFFl @ 


SRCOFFn @ 


* These fields are variable size. 
@ These fields are optional. 


FIGURE 7.59 

Import by Name Fixup Record. 


index into this table created by the loader to locate the referenced 
module. 

PROCEDURE NAME OFFSET = D[WID] Offset into the Import 
Procedure Name Table. 

This field is an offset into the Import Procedure Name Table. It 
is a Word value when the ‘32-bit Target Offset Flag’ bit in the 
target flags field is clear and a Dword value when the bit is set. 

ADDITIVE = D[WID] Additive fixup value. 

This field exists in the fixup record only when the ‘Additive 
Fixup Flag’ bit in the target flags field is set. When the ‘Additive 
Fixup Flag’ is clear the fixup record does not contain this field 
and is immediately followed by the next fixup record (or by the 
source offset list for this fixup record). 

This value is added to the address derived from the target entry 
point. This field is a Word value when the ‘32-bit Additive Flag’ 
bit in the target flags field is clear and a Dword value when the 
bit is set. 


ENTRY # = D[BIW] Ordinal index into the Entry Table. 

This field is an index into the current module’s Entry Table to 
specify the target Object and offset. It is a Byte value when the 
‘16-bit Object Number/Module Ordinal’ Flag bit in the target 
flags field is clear and a Word value when the bit is set. 

ADDITIVE = D[WID] Additive fixup value. 
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OOh 

03h/04h 


SRC 

FLAGS 

SRCOFF/CNT * 


ORD#* 

ADDITIVE * @ 

SRCOFFl @ 


SRCOFFn @ 


* These fields are variable size. 
@ These fields are optional. 


FIGURE 7.60 

Internal Entry Table Fixup Record. 


This field exists in the fixup record only when the ’Additive 
Fixup Flag’ bit in the target flags field is set. When the ’Additive 
Fixup Flag’ is clear the fixup record does not contain this field 
and is immediately followed by the next fixup record (or by the 
source offset list for this fixup record). 

This value is added to the address derived from the target entry 
point. This field is a Word value when the ‘32-bit Additive Flag’ 
bit in the target flags field is clear and a Dword value when the 
bit is set. 

Import Module Name Table 

The import module name table defines the module name strings imported 
through dynamic link references. These strings are referenced through the 
imported relocation fixups. 

To determine the length of the import module name table subtract the 
import module name table offset from the import procedure name table offset. 
These values are located in the linear EXE header. The end of the import 
module name table is not terminated by a special character, it is followed 
directly by the import procedure name table. 

The strings are CASE SENSITIVE and NOT NULL TERMINATED. 
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Each name table entry has the following format: 


OOh 


LEN 


ASCII STRING 


FIGURE 7.61 

Import Module Name Table. 


LEN = DB String Length. 

This defines the length of the string in bytes. The length of each 
ascii name string is limited to 255 characters. 

ASCII STRING = DB ASCII String. 

This is a variable length string with it’s length defined in bytes 
by the LEN field. The string is case sensitive and is not null 
terminated. 

Import Procedure Name Table 

The import procedure name table defines the procedure name strings im¬ 
ported by this module through dynamic link references. These strings are 
referenced through the imported relocation fixups. 

To determine the length of the import procedure name table add the fixup 
section size to the fixup page table offset, this computes the offset to the end 
of the fixup section, then subtract the import procedure name table offset. 
These values are located in the linear EXE header. The import procedure 
name table is followed by the data pages section. Since the data pages section 
is aligned on a ‘page size’ boundary, padded space may exist between the 
last import name string and the first page in the data pages section. If this 
padded space exists it will be zero filled. 

The strings are CASE SENSITIVE and NOT NULL TERMINATED. 

Each name table entry has the following format:. 


OOh 


LEN 


ASCII STRING 


FIGURE 7.62 

Import Procedure Name Table. 


LEN = DB String Length. 
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This defines the length of the string in bytes. The length of each 
ascii name string is limited to 255 characters. 

The high bit in the LEN field (bit 7) is defined as an Overload 
bit. This bit signifies that additional information is contained 
in the linear EXE module and will be used in the future for 
parameter type checking. 

ASCII STRING = DB ASCII String. 

This is a variable length string with it’s length defined in bytes 
by the LEN field. The string is case sensitive and is not null 
terminated. 


Note: The first entry in the import procedure name table must be a null 
entry. That is, the LEN field should be zero followed an empty ASCII 
STRING (no bytes). 

Preload Pages 

The Preload Pages section is an optional section in the linear EXE module 
that coalesces a ‘preload page set’ into a contiguous section. The preload 
page set can be defined as the set of first used pages in the module. The 
preload page set can be specified by the application developer or can be de¬ 
rived by a tool that analyzes the programs memory usage while it is running. 
By grouping the preload page set together, the preload pages can be read 
from the linear EXE module with one disk read. 

The structure of the preload pages is no different than if they were demand 
loaded. Their sizes are determined by the Object Page Table entries that 
correspond. If the specified size is less than the PAGE SIZE field given in 
the linear EXE module header the remainder of the page is filled with zeros 
when loaded. 

All pages begin on a PAGE OFFSET SHIFT boundary from the base of 
the preload page section, as specified in the linear EXE header. The pages 
are ordered by logical page number within this section. 

Note that OS/2 2.x does not respect the preload of pages as specified in 
the executable file for performance reasons. 


Demand Load Pages 

The Demand Loaded Pages section contains all the non-iterated pages for 
a linear EXE module that are not preloaded. When required, the whole page 
is loaded into memory from the module. The characteristics of each of these 
pages is specified in the Object Page Table. Every page begins on a PAGE 
OFFSET SHIFT boundary aligned offset from the demand loaded pages base 
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specified in the linear EXE header. Their sizes are determined by the Object 
Page Table entries that correspond. If the specified size is less than the PAGE 
SIZE field given in the linear EXE module header the remainder of the page 
is filled with zeros when loaded. The pages are ordered by logical page 
number within this section. 

Iterated Data Pages 

The Iterated Data Pages section contains all the pages for a linear EXE 
module that are iterated. When required, the set of iteration records are 
loaded into memory from the module and expanded to reconstitute the page. 
Every set of iteration records begins on a PAGE OFFSET SHIFT offset from 
the OBJECT ITER PAGES OFF specified in the linear EXE header. Their 
sizes are determined by the Object Page Table entries that correspond. The 
pages are ordered by logical page number within this section. 

This record structure is used to describe the iterated data for an object on 
a per-page basis. 


OOh 

04h 


#ITERATIONS 

DATA LENGTH 


DATA BYTES 




FIGURE 7.63 

Object Iterated Data Record (Iteration Record). 


#ITERATIONS = DW Number of iterations. 

This specifies the number of times that the data is replicated. 
DATA LENGTH = DW The size of the data pattern in bytes. 

This specifies the number of bytes of data of which the pattern 
consists. The maximum size is one half of the PAGE SIZE 
(given in the module header). If a pattern exceeds this value 
then the data page will not be condensed into iterated data. 

DATA = DB * DATA LENGTH The Data pattern to be replicated. 

The next iteration record will immediately follow the last byte 
of the pattern. The offset of the next iteration record is easily 
calculated from the offset of this record by adding the DATA 
LENGTH field and the sizes of the ITERATIONS and DATA 
LENGTH fields. 
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Debug Information 

The debug information is defined by the debugger and is not controlled 
by the linear EXE format or linker. The only data defined by the linear EXE 
format relative to the debug information is it’s offset in the EXE file and 
length in bytes as defined in the linear EXE header. 

To support multiple debuggers the first word of the debug information is 
a type field which determines the format of the debug information. 

OOh Olh 02h 03h 04h _ 

‘N’ ‘B’ ‘0’ n DEBUGGER DATA... 


FIGURE 7.64 
Debug Information. 


TYPE = DB DUP 4 Format type. 

This defines the type of debugger data that exists in the remain¬ 
der of the debug information. The signature consists of a string 
of four (4) ASCII characters. “NBO” followed by the ASCII 
representation for ‘n’. The values for ‘n’ are defined as follows. 

These format types are defined. 

OOh = 32-bit CodeView debugger format. 

Olh = AIX debugger format. 

02h = 16-bit CodeView debugger format. 

04h = 32-bit OS/2 PM debugger (IBM) format. 

DEBUGGER DATA = Debugger specific data. 

The format of the debugger data is defined by the debugger that 
is being used. 

The values defined for the type field are not enforced by the 
system. It is the responsibility of the linker or debugging tools 
to follow the convention for the type field that is defined here. 
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of the SOFTWARE for backup or archival purposes only. You may be held legally respon¬ 
sible for any copying or copyright infringement which is caused or encouraged by your 
failure to abide by the terms of this restriction. 

4. USE RESTRICTIONS: You may not network the SOFTWARE or otherwise 
use it on more than one computer or computer terminal at the same time. You may physi¬ 
cally transfer the SOFTWARE from one computer to another provided that the SOFT¬ 
WARE is used on only one computer at a time. You may not distribute copies of the SOFT¬ 
WARE or Documentation to others. You may not reverse engineer, disassemble, decom¬ 
pile, modify, adapt, translate, or create derivative works based on the SOFTWARE or the 
Documentation without the prior written consent of the Company. 

5. TRANSFER RESTRICTIONS: The enclosed SOFTWARE is licensed only to 
you and may not be transferred to any one else without the prior written consent of the 
Company. Any unauthorized transfer of the SOFTWARE shall result in the immediate ter¬ 
mination of this Agreement. 

6. TERMINATION: This license is effective until terminated. This license will 
terminate automatically without notice from the Company and become null and void if you 
fail to comply with any provisions or limitations of this license. Upon termination, you 
shall destroy the Documentation and all copies of the SOFTWARE. All provisions of this 
Agreement as to warranties, limitation of liability, remedies or damages, and our owner¬ 
ship rights shall survive termination. 

7. MISCELLANEOUS: This Agreement shall be construed in accordance with 
the laws of the United States of America and the State of New York and shall benefit the 
Company, its affiliates, and assignees. 

8. LIMITED WARRANTY AND DISCLAIMER OF WARRANTY: The 
Company warrants that the SOFTWARE, when properly used in accordance with the 



Documentation, will operate in substantial conformity with the description of the SOFT¬ 
WARE set forth in the Documentation. The Company does not warrant that the SOFT¬ 
WARE will meet your requirements or that the operation of the SOFTWARE will be unin¬ 
terrupted or error-free. The Company warrants that the media on which the SOFTWARE 
is delivered shall be free from defects in materials and workmanship under normal use for 
a period of thirty (30) days from the date of your purchase. Your only remedy and the 
Company’s only obligation under these limited warranties is, at the Company’s option, 
return of the warranted item for a refund of any amounts paid by you or replacement of the 
item. Any replacement of SOFTWARE or media under the warranties shall not extend the 
original warranty period. The limited warranty set forth above shall not apply to any 
SOFTWARE which the Company determines in good faith has been subject to misuse, 
neglect, improper installation, repair, alteration, or damage by you. EXCEPT FOR THE 
EXPRESSED WARRANTIES SET FORTH ABOVE, THE COMPANY DISCLAIMS 
ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITA¬ 
TION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE. EXCEPT FOR THE EXPRESS WARRANTY SET FORTH 
ABOVE, THE COMPANY DOES NOT WARRANT, GUARANTEE, OR MAKE ANY 
REPRESENTATION REGARDING THE USE OR THE RESULTS OF THE USE OF 
THE SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, 
CURRENTNESS, OR OTHERWISE. 

IN NO EVENT, SHALL THE COMPANY OR ITS EMPLOYEES, AGENTS, 
SUPPLIERS, OR CONTRACTORS BE LIABLE FOR ANY INCIDENTAL, INDIRECT, 
SPECIAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN CONNEC¬ 
TION WITH THE LICENSE GRANTED UNDER THIS AGREEMENT, OR FOR LOSS 
OF USE, LOSS OF DATA, LOSS OF INCOME OR PROFIT, OR OTHER LOSSES, 
SUSTAINED AS A RESULT OF INJURY TO ANY PERSON, OR LOSS OF OR DAM¬ 
AGE TO PROPERTY, OR CLAIMS OF THIRD PARTIES, EVEN IF THE COMPANY 
OR AN AUTHORIZED REPRESENTATIVE OF THE COMPANY HAS BEEN 
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT SHALL LIA¬ 
BILITY OF THE COMPANY FOR DAMAGES WITH RESPECT TO THE SOFTWARE 
EXCEED THE AMOUNTS ACTUALLY PAID BY YOU, IF ANY, FOR THE SOFT¬ 
WARE. 


SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OF IMPLIED 
WARRANTIES OR LIABILITY FOR INCIDENTAL, INDIRECT, SPECIAL, OR CON¬ 
SEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS MAY NOT ALWAYS 
APPLY. THE WARRANTIES IN THIS AGREEMENT GIVE YOU SPECIFIC LEGAL 
RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS WHICH VARY IN ACCOR¬ 
DANCE WITH LOCAL LAW. 


ACKNOWLEDGMENT 

YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, 
UNDERSTAND IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDI¬ 
TIONS. YOU ALSO AGREE THAT THIS AGREEMENT IS THE COMPLETE AND 
EXCLUSIVE STATEMENT OF THE AGREEMENT BETWEEN YOU AND THE COM¬ 
PANY AND SUPERSEDES ALL PROPOSALS OR PRIOR AGREEMENTS, ORAL, OR 
WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN YOU AND THE 
COMPANY OR ANY REPRESENTATIVE OF THE COMPANY RELATING TO THE 
SUBJECT MATTER OF THIS AGREEMENT. 

Should you have any questions concerning this Agreement or if you wish to con¬ 
tact the Company for any reason, please contact in writing at the address below or call the 
at the telephone number provided. 

PTR Customer Service 
Prentice Hall PTR 
One Lake Street 

Upper Saddle River, New Jersey 07458 


Telephone: 201-236-7105 



LICENSE AGREEMENT 
AND LIMITED WARRANTY 

READ THE AGREEMENT FOLLOWING THE INDEX AND 
THIS LABEL BEFORE OPENING MEDIA PACKAGE. 

BY OPENING THIS SEALED MEDIA PACKAGE, YOU ACCEPT AND 
AGREE TO THE TERMS AND CONDITIONS PRINTED BELOW. IF 
YOU DO NOT AGREE, DO NOT OPEN THE PACKAGE. SIMPLY 
RETURN THE SEALED PACKAGE. 

The enclosed media is distributed on an “AS IS” basis, without warranty. 
Neither the authors, the software developers if any nor Prentice Hall make 
any representation, or warranty, either express or implied, with respect to the 
media content, their quality, accuracy, or fitness for a specific purpose. 
Therefore, neither the authors, the software developers nor Prentice Hall 
shall have any liability to you or any other person or entity with respect to 
any liability, loss, or damage caused or alleged to have been caused directly 
or indirectly by the contents of the media. This includes, but is not limited 
to, interruption of service, loss of data, loss of classroom time, loss of con¬ 
sulting or anticipatory profits, or consequential damages from the use of the 
media content. If the media is defective, you may return it for replacement. 
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A Note About Tools and Samples 

All of the samples in this book are included on the accompanying 
diskette. Most samples have makefiles for your convenience. Each 
sample is in its own directory. There is a README file in the 
root directory of the diskette. We have also included the object 
files, executables and other files mentioned in the text such as 
EXEHDR.EXE output. If you want to copy the samples to your 
fixed disk, you can use the OS/2 XCOPY command. This should 
only be necessary if you plan to recompile or experiment with the 
samples. We make the assumption that you are familiar with the C 
programming language, have a C compiler installed and that your 
environment variables are set up correctly to perform compilations. 
Refer to your compiler user’s guide for the proper settings. We used 
the IBM C Set++ compiler, but with only standard ANSI C library 
functions, so it should be easy to port the samples to work with 
any popular C compiler. The OS/2 tools we used, such as 
LINK386.EXE, EXEHDR.EXE and FWDSTAMP.EXE are the ver¬ 
sions on the most recent Developer Connection for OS/2 which is a 
subscription service from IBM aimed specifically at software devel¬ 
opers. As of this writing, Developer Connection Volume #8 is the 
current release. For further details call toll free at 1-800-6DEVCON 
(1-800-633-8266). While desirable, most of the material in this book 
does NOT require the tools. All samples include source and running 
executables. 
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